This tutorial is designed to teach users how to create executable files from source code. I also provide details that should help users build source code from other developers. The information is provided as follows: (1) The basic instructions for each step are given on the left. These are all you need if you want to get a piece of software up and running quickly and aren't really interested in doing it in the future. (2) Detailed descriptions are given on the right. I describe why each step in the build process is necessary and discuss other options that are commonly used by developers.
Step 1: Get a compiler and linker
Windows: Visual Studio
I recommend avoiding the Express edition of Visual Studio if at all possible. Most universities have appropriate licenses for the Professional edition. Students can also download the most recent versions of Visual Studio through Dreamspark.
Linux: GCC and G++. Check your package manager (ex. Synaptic for Ubuntu). An appropriate IDE (ex. Eclipse or Code::Blocks) is also helpful.
A compiler and linker are the main applications used to create an executable program from C/C++ source code. When compiling and linking pre-developed source code, both processes are generally thought of as a single build operation. Several tools are available, depending on the hardware and operating system. For Windows systems, the most popular tools include Microsoft's Visual Studio and Borland C++. In addition to compiling and linking, these software environments also contain tools to aid in coding and debugging.
Step 2: Get CMake
You can download the binary distribution for your platform at this website: www.cmake.org
Make sure to get the binary file (executable). They tend to list the source code first, which you don't need. If you're using Windows, the Win32 Installer is the most convenient.
CMake is a cross-platform build tool maintained by Kitware. This program takes as input a text file named CMakeLists.txt, which describes the process required to create an executable. This includes additional compiling and linking steps, as well as all any additional libraries and parameters that are necessary. CMake outputs a build environment appropriate for your compiler (ex. a Visual Studio solution or a GCC Makefile).
Step 3: Download the source code repository
This can be done in two ways:
(A) As a ZIP archive (easiest):
Go to a GitHub page and select the ZIP option
Unzip the archive into a folder
(B) Using GIT:
Download and install GIT
Create a folder to store the source code
Go to the folder and type: git clone [repository name]
Replace [repository name] with the GitHub address
There are several different methods used to track and distribute source code. They are all relatively easy to use and many websites aid open-source development by providing free online hosting. Popular options include Subversion (SVN), the Concurrent Versions System (CVS), and Git. The STIM lab uses Git, which is known for its "branching" ability, which allows a developer to simultaneously maintain multiple versions of a repository. This allows us to fix bugs in one version of the code while concurrently creating new features for a later release.
Step 4: Download any necessary libraries
Here is a short list of libraries that are frequently used in STIM Lab applications:
stimlib. This is a codebase developed and used extensively in the STIM Lab. You can clone the repository here. Set the STIMLIB_PATH environment variable to the repository directory and CMake will be able to find it.
Qt. The Qt Project is a cross-platform graphical user interface (GUI) library.
CUDA. The CUDA programming platform was developed by nVidia in order to do general purpose computation on graphics hardware. I use this library extensively. Finding new methods for taking advantage of parallel computation is a major focus of my work. However, it is constantly under development and can be pretty difficult to use. If you are interested, I recommend the book "Cuda by Example" as a starting point. The language is very similar to C.
GLEW. The OpenGL Extension Wrangler Library is used to activate certain features in OpenGL for new graphics cards. Most of my visualization applications use this.
ANN. The Approximate Nearest Neighbor library has several algorithms that are useful for solving k-nearest neighbor and similar problems.
BOOST. The BOOST C++ libraries are a series of template libraries that provide a range of useful functions, including algorithms for solving mathematical problems, such as image processing, complex functions, and graph theory.
Step 5: Configure your build environment
Select your compiler (from step 1).
Enter the location of the source code.
Enter a [destination] folder where you want to build the software.
Click
configureIf an error occurs, you're probably missing a library
just download it and click configure again.
If you DID download the library, maybe CMake can't find it
enter the library location manually and click configure again.
If the configuration is successful (no errors), click
generate
Load CMake and specify both the location of the CMakeLists.txt file (usually in the source directory) and the destination folder where you want the build to take place. This will load a table of variables, most of which will be highlighted in red. These variables are what CMake requires in order to set up the build environment. They include the locations of any necessary software, such as compilers, libraries, or additional source code. Most of these will be determined automatically by CMake, but some may require user-input.
Click configure in order to start the process. CMake will first ask you what build environment you want to use: select the one that you installed in step 1. CMake will then try to locate all of the stuff needed to build the application.
When CMake is unable to find something, it will issue an error identifying the problem and highlight the associated variable(s) in red. Fix the problem by downloading the necessary software and/or setting its location in the table.
Repeat until you can configure without any errors. You will receive a message that the configuration was successful. Click generate to create a build environment in the specified destination directory. This will be something like a Visual Studio solution (*.sln) file for Windows, or a GNU Makefile for Linux.
Step 6: Compile and run
Go to the [destination] folder that you specified in step 5
Windows: (a) Open the *.sln file, (b) right click on the software name and select "Set as Startup Project", and (c) Rebuild the project (F7). You may also want to set the build mode to "Release" for for optimization.
MacOS: -----
Linux: Type make and then run the created executable
Now you can compile the software. The method for doing this depends on the build system. I can explain the process for the ones that I use:
Visual Studio (Windows). Load the solution (*.sln) file into Visual Studio. You will likely have a project tree on the left and several options in the menu bar at the top of the VS window. The project tree may contain a couple of projects, one of which is named ALL_BUILD. Another will be the name of the project you want to compile. By default, ALL_BUILD will be set as the default project (the name will be in bold). This is a quirk with CMake + VS that I don't think can be changed during configuration. Change the default project to the desired one (probably the second in the tree) by right-clicking and selecting "Set as Startup Project".
Now you can compile and link the code using the "Build" menu or by pressing the green "play" button at the top of the screen. Depending on your version of VS, you may also have the option to select the build type: either "Debug" or "Release". You probably want to compile the code in Release mode, since this is more efficient. Debug mode compiles the software with several features that make development easier, but greatly slow down the code (often by about 10X).
GCC (Linux). Go to the build directory and type make This will compile and link the code. Run the resulting executable by typing ./filename.