How to install 3DNA on Linux and Windows?

[xiangjun]

3DNA is a command-line driven software tool, developed and tested in Linux/Mac OS X systems. It can also be easily installed on other Unix variants, including Cygwin and MinGW/MSYS in Windows. The following instructions are targeted on two typical scenarios: one for Linux, and the other for MinGW/MSYS-based Windows.

As of 3DNA v2.1, Ruby has replaced Perl as the scripting language. Therefore, you must also have Ruby installed on your system. 3DNA has no dependence on any third-party gem, and has been tested on Ruby 1.8.x and 1.9.x series. Even though Ruby may not be installed by default on your system, the software is widely available on all common OSes, and should be straightforward to install.

As of 3DNA v2.3-2016sept06, the C source code is available (under the folder $X3DNA/src).

On Linux (including Mac OS X, or Cygwin on Windows)Assuming the downloaded tarball file is named x3dna-v2.3-linux-64bit.tar.gz. At your current working directory (presumably your home directory), do the following:

• tar pzxvf x3dna-v2.3-linux-64bit.tar.gz
  Here the options pzxvf require some explanation:
  
  • p to preserve permissions of the various directories and files. This option may not be required for a personal setting.
  • z filter the archive through gzip. With this option, we can work directly from .tar.gz file without first using gunzip.
  • x to extract files from an archive.
  • v to verbosely list files processed.
  • f to use archive file, i.e., the 3DNA tarball file x3dna-v2.3-linux-64bit.tar.gz.
    
  After running the above command, you will get a directory named x3dna-v2.3 which contains the 3DNA v2.3 distribution.
  
• cd x3dna-v2.3/bin
  enter into the bin directory of the 3DNA v2.3 distribution.
• ./x3dna_setup
  run the 3DNA setup Ruby script, and you will see an output similar to the following:
  

  To install X3DNA, do as follows:
    (0) download 3DNA binary distribution for your system from URL
            http://x3dna.org
    (1) tar pzxvf x3dna-v2.3-linux-64bit.tar.gz
    (2) cd x3dna-v2.3/bin
    (3) ./x3dna_setup
          To run X3DNA, you need to set up the followings:
            o the environment variable X3DNA
            o add $X3DNA/bin to your command line search path
            for your 'bash' shell, please add the following into ~/.bashrc:
            --------------------------------------------------------------
              export X3DNA='/home/xiangjun/x3dna-v2.3'
              export PATH='/home/xiangjun/x3dna-v2.3/bin':$PATH
            --------------------------------------------------------------
            and then run: source ~/.bashrc
    (4) type find_pair -h
          for command line help -- this applies to all 3DNA binaries
          Visit 3DNA homepage at URL http://x3dna.org/ for more info.

  Here the key parts are colored red, i.e., set the environment variable X3DNA and add $X3DNA/bin to your command search path.
  
  The above example refers to the most commonly used 'bash' shell. For the 'sh' shell, the 'x3dna_setup' output would be:

            for your 'sh' shell, add the following into ~/.profile:
            --------------------------------------------------------------
                export X3DNA='/home/xiangjun/x3dna-v2.3'
                export PATH='/home/xiangjun/x3dna-v2.3/bin':$PATH
            --------------------------------------------------------------
            and then run: source ~/.profile

  You may need to use the dot command: . ~/.profile. For the 'tcsh' (or 'csh') shell, the 'x3dna_setup' output would be:

            for your 'tcsh' shell, add the following into ~/.cshrc:
            --------------------------------------------------------------
              setenv X3DNA '/home/xiangjun/x3dna-v2.3'
              setenv PATH '/home/xiangjun/x3dna-v2.3/bin':$PATH
            --------------------------------------------------------------
            and then run: source ~/.cshrc

  If your shell is none of the four recognized ones -- bash, sh, tcsh, or csh -- or cannot be detected, the script still outputs sensible settings about the installation.
• find_pair -h
  or ./find_pair -h if you've strictly followed the steps above, and your current working directly is not in the command search path. Now you should see a screenful of command-line help. Congratulations -- You now have 3DNA properly installed! If otherwise, please post here with details, and we will try to help you out.
  

On native Windows (added on July 14, 2017)See FAQ entry: "How to set up 3DNA on Windows"?

On MinGW/MSYS--based WindowsFirst, you need to install MSYS2 and Ruby on Windows. Depending on your experience, you may need to seek help from local experts. The following is a general guideline to get you started. Overall, it should be quite straightforward.

• Use MSYS2 installer to install MSYS2, either 32-bit or 64-bit is fine. I've found MSYS2 to be simpler to install than the original MinGW/MSYS system.
• Then install the latest version of Ruby with "Ruby Installer". In the "Installation Destination and Optional Tasks" section, be sure to select "Add Ruby executables to your path", and "Associate .rb and .rbw files with this Ruby installation".

After installing MinGW/MSYS, double-click the "M" (msys) icon on the desktop to start the MSYS shell.. See the thread "How to install 3DNA on MinGW/MSYS".

Then follow the instructions above on installing 3DNA on Linux.

Compile 3DNA from the source code

• Follow step #1 for Linux (above) to extract the 3DNA tarball to its own folder (x3dna-v2.3)
• cd x3dna-v2.3/src
  Then type make
  The gcc compiler is assumed in the Makefile. If you have a non-gcc compiler, you should modify the following two lines as appropriate:
  

  CFLAGS      = -ansi -pedantic -W -Wall -Wextra -Wunused -Wshadow  -O3
  CC      = gcc

  Since 3DNA is implemented in strict ANSI C, it should compile without any changes with any modern C compiler.
  Then follow steps 2-4 above for Linux to set the X3DNA and PATH environment variables.