Note: If you encounter problems you may want to first check the new "How to build" pages on the right side bar, under "For Developers". Literally you may want to check the following pages:

• https://github.com/Vaa3D/Vaa3D_Wiki/wiki/Build-Vaa3D-on-Linux
• https://github.com/Vaa3D/Vaa3D_Wiki/wiki/Build-Vaa3D-on-Mac-OS
• https://github.com/Vaa3D/Vaa3D_Wiki/wiki/Build-Vaa3D-on-Windows-%28QMake%29

Read on for general information.

You should have both Qt and C++ compiler ready on your system.

You can get Qt from

http://qt-project.org/downloads

Supported Qt versions

Note, some of the newer versions of Qt (e.g. Qt 4.8.7 +) might not be compatible with some of operating systems (e.g. Mac 10.10). To avoid these problems, you can download a relatively stable Qt version, e.g. 4.8.6, from the following link.

https://download.qt.io/archive/qt/

In case you cannot compile the required Qt library with the latest Command Line Tools (XCode 6.0 or higher), you can grab a pre-compiled binary library, which has been tested for most common OS platforms using the qmake and shell script (when building using CMake, qt 4.7.1 may not work with some of the default c++ compilers, for example Mac OS X 10.9.5 and its LLVM 3.5) , as follows:

1. (Mac only ) Download the precompiled Qt 4.7.1 library from this link
   

• open the Terminal and go to your home directory
  
• create (or edit) the .bash_profile file with a command line editor (e.g. nano)
  

    nano .bash_profile
  
  

• add the line
  

    export PATH="/usr/local/Trolltech/Qt-4.7.1/bin:$PATH"
  
  

which declares the new location /usr/local/Trolltech/Qt-4.7.1/bin as well as the original path declared as $PATH.

• save the file in nano by clicking control+o and confirming the name of the file is .bash_profile by hitting return. And the control+x to exit nano
• relaunch the Terminal and check that your qmake works by typing
  

    qmake --version
  
  

which should produce

 QMake version 2.01a

 Using Qt version 4.7.1 in /usr/local/Trolltech/Qt-4.7.1/lib

Note:

For those who have installed Qtlib using Qt Installer directly, and at the same time also have other Qt versions installed, the computer might be messed up in a way it might not be clear which Qt library would be linked during building. To resolve the issue, one can revise the corresponding building script (build.macx for Mac and build.linux for Linux) by adding the following statements at the beginning (let's use Qt 4.7.1 as an example)

QT4=<QT_4.7.1_PATH>

PATH=$QT4/bin:$PATH

QMAKESPEC=$QT4/mkspecs/<spec>

Here <QT_4.7.1_PATH> is the placeholder for the directory where Qt 4.7.1 is installed and <spec> is the placeholder for specification. For example, <spec> can be macx-g++ for Mac OS and linux-g++ for Linux, depending on what C++ complier you want to use.

http://code.google.com/p/qt-msvc-installer/ 

Ensure that if you have a 32bit system, you will need the 32bit installer; if you have a 64bit Windows system, you should download the 64bit installer.

2. Add Qt’s bin directory to your system PATH environment variable, so that on a command line window you can find “qmake” command.

3. Select and run the 32bit or 64bit command line Terminal in the Visual Studio 2008 (or similar compilers) folder. This will give you a command line window.

You need to check out source code from github code repositories, one for main Vaa3D code and one for some released plugins. You can following the instructions for both Vaa3D program and its default plugins.

First, make sure you have GIT installed.

git clone https://github.com/Vaa3D/v3d_external.git

git clone https://github.com/Vaa3D/vaa3d_tools.git

cd vaa3d_tools

ln -s ../v3d_external/v3d_main v3d_main

ln -s ../v3d_external/bin bin

cd ../v3d_external

ln -s ../vaa3d_tools/released_plugins released_plugins_more

cd vaa3d_tools

mklink /j  v3d_main ..\v3d_external\v3d_main

mklink /j  bin ..\v3d_external\bin

cd ..\v3d_external

mklink /j  released_plugins_more  ..\vaa3d_tools\released_plugins

build.macx -B -m -j4

# or running the alterative for Linux

# build.linux -B -j4

The last few lines create symbolic links for necessary header files and output plugins.

You may replace the "-j4" using "-j8", "-j2", or "-j16", depending on how many CPU cores your have on your machine. Note that the "make" command on some systems (e.g. Ubuntu) may not recognize the "-j" parameter. In such as case, you can just run "build.linux" without that parameter.

Note that for some Linux systems, such as CentOS, the standard OpenGL and GLUT library files might be missing. Thus Vaa3D might have some trouble to be built. You may need to run the following commands (or sth similar) to first get these files (also note that you may need to do this even before Qt is built and installed, as on Linux the OpenGL support in Qt is dependent on the status of the operating system)

yum install freeglut

yum install mesa-libGL-devel mesa-libGLU-devel

On a fresh Linux (e.g. CentOS) system, you may not even have git, g++, Xext, etc. You can install them via the following commands:

sudo yum install git

sudo yum install gcc-c++

sudo yum install libXext-devel.x86_64

sudo yum install libXrender-devel.x86_64

In case you don't know the exact names of the missing system library files, you can try to search using the following command (for the xext example) to figure out the exact name(s).

sudo yum search  xext

sudo yum whatprovides xext

Check out Vaa3D source code from github

https://github.com/Vaa3D/v3d_external.git

To build Vaa3D (32bit and 64bit) on Windows 7 (64bit) using MS Visual Studio 2008 / Visual C++ Express / etc, please follow the instructions below:

1. Open "Visual Studio 2008 Command Prompt" (for 32bit building) window or "Visual Studio 2008 x64 Win64 Command Prompt" (for 64bit building) window from "MS Visual Studio 2008 -> Visual Studio Tools" menu item in Windows Start menu
   
2. Make sure you have the correct Qt 32bit or 64bit versions installed, as the "qmake" command below will have an impact of whether x86 or x86_64 (x64) MSVC project files would be generated! (Note: we recommend you use the Qt 4.7.2 binary downloadable from here https://qt-msvc-installer.googlecode.com/files/qt-win64-opensource-4.7.2-vs2008.exe as newer versions of Qt for Windows, e.g. 4.8, seemingly has changed the plugin interface which makes our plugins difficult to unload and re-instantiate!)
   
3. Make sure you have "boost" library header files in the "v3d_main\common_lib\include" folder. If not, you can copy the "boost" folder into "v3d_main\common_lib\include" after you untar the boost_1_46_0.tar.gz file in the "v3d_main\common_lib\src_packages" folder.
   
4. Make sure you have libtiff header files in the "v3d_main\common_lib\include" folder. If not, you can extract the all tiff header (.h) files in the "tiff-4.0.2\libtiff" folder after you untar the tiff-4.0.2.tar.gz file in the "v3d_main\common_lib\src_packages" folder.
   
5. Make sure you have fftw header file (fftw3.h) in "v3d_main\common_lib\include" folder. If not, you can copy the header from "fftw_3.3_header" in the "v3d_main\common_lib\src_packages" folder. Pugins like istitch relies on fftw library.
   
6. Enter "v3d_main\v3d" folder
   
7. Run "qmake -tp vc vaa3d_msvc.pro". This command creates a MS Visual Studio 2008 project file "vaa3d_msvc.vcproj" in "v3d_main\v3d" folder
   
8. Double click "vaa3d_msvc.vcproj" in "v3d_main\v3d" folder and open it in MS Visual Studio 2008
   
9. Choose building in "Release" mode in MS Visual Studio 2008
   
10. Choose building in "Win32" (for 32bit building) or "x64" (for 64bit building) mode in vaa3d_msvc Property Pages (by right-click v3d_msvc project icon in the left column in workspace in MS Visual Studio 2008) or just on the toolbar.
    
11. Choose menu "Build->Build Solution F7" to build the solution. A popup dialog will appear to ask to save solution file for this project. Just click "OK" in this dialog
    
12. Now Vaa3D has been built. You can find the executable from the location "v3d_main\v3d\release\vaa3d_msvc.exe".
    
13. To run the executable, you will have to make the dependency Qt library files etc available to it. Thus the simplest way is to download the pre-generated binary package of Vaa3D Windows version, unzip the package, and then use the "vaa3d_msvc.exe" file you have just generated to replace the one (with the same file) in the unzipped package (which already have all dependency files included). Of course, since the pre-generated Vaa3D Windows version may be produced from a different Qt version, a different MSVC version, a different Release or Debug version, and may have different Vaa3D plugins, you need to make sure you have consistent files. A simple way is to rebuild everything using your own local settings, and put the necessary files (see the pre-generated binary package for the file list) under the same folder to run!
    
14. Note that if a previous MSVC solution file already exists, and you constantly have trouble to link to the latest compiling modules successfully, then you may need to manually delete the previously generated MSVC solution file first, and then use the "vaa3d_msvc.vcproj" following the above instructions!

The building method works for both 32bit and 64bit buildings.

If you are using Visual Studio 2010, then you may need to rebuild Qt before you build Vaa3D.

The following procedure has been working well for us on Mac. (For Windows builds, use the cmake build system, described in the next section, below).

1. Checkout code from GITHUB Branch Location

    https://github.com/Vaa3D/v3d_external.git

1. Start Qt Creator
   
2. File -> New File Or Project -> Other Project -> Import Existing Project
   
3. Name the project (for the files) and choose the development dir
   
4. In Qt Creator, on left select Projects and Remove "make all"
   
5. Add build step: Command is "./build.macx", Command args are "-m -j4" (some of this comes from the README file of the project)

In addition to the shell script/qmake based build system described above, there is a parallel build system based on CMake. Some of the differences between the qmake and CMake build system are as follows:

• CMake does an "out of source" build by default, meaning that generated files such as object files, binaries, and machine-generated sources are not mixed together in the same directories as the original source code. Some developers find this approach to be tidier.
  
• The same CMake build scripts will work on Windows, Mac, and Linux. That "build.macx" script in the qmake VAA3D build system is specific to Mac computers.
  
• CMake is used with its allied tool CPack to conveniently create platform-specific installers. This can help create an aura of professionalism. For example, on the Mac the installer creates a .dmg file that, when opened, shows a license agreement, followed by a convential drag-this-app-to-the-Applications-folder Finder window.
  
• The current CMake build system requires the build user to manually build some third party libraries. This is not so much a fundamental difference between CMake and the build.macx script, as a historical accident of me not having yet written the CMake code to build those libraries automatically.
  
• The current CMake build system creates Universal fat binaries that run on both 32-bit and 64-bit Mac systems. This is one of several ways that the CMake-produced binaries are a bit more portable than the qmake-produced binaries. Again, this is a historical difference between the two build systems, not a fundamental one.

Use some Windows machine, where we have already installed all of the prerequisites.

1. Install Visual Studio 2010 Professional. You need the "Professional" version to be able to build 64-bit binaries. NeuronAnnotator needs to be built in 64-bit mode.
   
2. Install CMake. CMake is the meta build system we use for Vaa3D. Instead of using qmake.
   
3. Install git. You can search for a convenient graphical git source control client for Windows.
   
4. Install 7zip. 7zip is a great free tool for unpacking zip, gz, and tar files on Windows.
   
5. Install NSIS. NSIS is a free Windows installer maker. Building the PACKAGE target in our Visual Studio project will create an NSIS Vaa3D installer.
   
6. Install Perl. Make sure perl is on your PATH. I like to use Path Editor to manipulate the Windows path. Perl is needed for the Qt build from source process.
   
7. Install fftw. Don't forget to create the lib files (i.e. follow the directions). This fast Fourier transform library is used by the Vaa3D istitch plugin. Add the fftw library location to your PATH.
   
8. Install Qt version 4.7.4 built using MSVC10 in 64-bit mode. You probably need to build it yourself, unless you can find it here or here. Last time I looked, those sites only had binaries for 32-bit platforms, or for MSVC2008. You need 64-bit MSVC2010.
   
9. Unpack the qt source code exactly where you want the binaries to end up. Because the qmake tool remembers where it was built, and expects to still be there. Probably build it under "C:\Qt\4.7.4_x64_MSVC2010\" ftp://ftp.qt.nokia.com/qt/source/qt-everywhere-opensource-src-4.7.4.zip
   • Put the new Qt bin folder on your PATH.
     
   • Launch the "Visual Studio x64 Win64 Command Prompt" from Start->Microsoft Visual Studio 2010->Visual Studio Tools->Visual Studio x64 Win64 Command Prompt

            Follow the build instructions at http://doc.qt.nokia.com/4.7-snapshot/install-win.html.

            cd \Qt\4.74_x64_MSVC2010

            configure

            nmake

1. Check out Vaa3D source code from the github repository. URL:
   

   https://github.com/Vaa3D/v3d_external.git
   
   

2. (Windows) Inside the Vaa3D v3d_main/common_lib/src_packages/ folder,
   
   • unpack boost_1_46_0.tar.gz to create the folder boost_1_46_0/ (using 7zip).
     
   • unpack version 4.0.1 libtiff source code http://download.osgeo.org/libtiff/tiff-4.0.1.zip to create the folder tiff-4.0.1/
     
3. Create folder "build_cmake" under your top level vaa3d folder.
   
4. Install Qt if you have not done so already: http://qt.nokia.com/downloads)
   
5. Install cmake if you have not done so already: http://www.cmake.org/cmake/resources/software.html
6. Launch the CMake GUI and set the source directory to the development dir, and set the build directory to the build_cmake folder you created in step 2.
   
7. For Mac OS X 10.8+, please set CMAKE_CXX_FLAG = -stdlib=libstdc++ ( to avoid QT related errors).
   
8. Press the "Configure" button. On Mac, select "Unix Makefiles" as the generator type, when prompted. (Even if you use Eclipse IDE, select "Unix Makefiles"; trust me). Troubleshoot any error or warning messages that appear. This is the point where you might need to manually build some libraries. Look over the displayed parameter values.
   
9. Keep pressing "Configure" until the "Generate" button becomes enabled. Press Generate.
   
10. (Windows) Open the new Vaa3D.sln file in the build_cmake folder with Visual Studio 2010 Professional. In the combobox pulldowns on the toolbar, select "Release" mode and "x64" platform. In the Solution Explorer panel on the left, right click the ALL_BUILD rule and select "Build". When that completes, right click the v3d target, and select "Set as Startup Project". Now type "ctrl-F5" to launch Vaa3D from the IDE.
    
11. (Mac and Linux) Manually build VAA3D for the first time by opening a Terminal, cd to the build_cmake directory you created, and type "make".
    
12. Configure your IDE to build VAA3D by issuing the "make" command in the build_cmake directory.
    
13. (Mac and Linux) If you use Eclipse IDE, follow the instructions at http://www.itk.org/Wiki/CMake:Eclipse_UNIX_Tutorial, under "Option 2". Also install the CMake Editor plugin, to get nice CMake syntax highlighting.
    
14. Build the "package" target to make an installer for your platform. On linux and Mac, "make package" at the command line. On windows, build the PACKAGE target in Visual Studio.