Package Compilation

Package Compilation

Obtaining the source code

The latest EMsoft public release can be obtained from GitHub. Make sure you have your own GitHub user account; log in, and fork the develop branch from [https://github.com/EMsoft-org/EMsoft] into your own GitHub account. Then, on your own local computer, use the following command:

	git clone -b develop https://github.com/YOUR-USER-NAME/EMsoft EMsoftPublic

The final argument can be used to set the name of the folder that will contain the source code; if omitted, the default EMsoft will be used. You can use a full path name to direct the source code to the correct location, or create the folder inside the folder from which you execute this command. The cloning operation should take about 30 seconds or so, and will install the source code and related resources; the following folders will be created:

• IDL: contains a number of useful routines for users who have an IDL (Interactive Data Language) license;
• NamelistTemplates: contains name list template files for all EMsoft programs;
• Source: this is the main source code folder;
• Support: contains CMake support routines to build the package;
• manuals: contains LaTeX sources and PDF files with manuals for selected programs (this will be superceded by the on-line wiki pages);
• opencl: contains OpenCL scripts to execute code on the GPU (Graphical Processing Unit);
• resources; contains various resource files used by the EMsoft programs.

A few additional files are also available in the top folder, including the License.txt file describing the copyright license for the EMsoft package, and a general ReadMe.md file.

Building the EMsoft package

Before you build the package, make sure that the location of the CMake program is added to your shell PATH variable; the syntax will depend on the type of shell you are using. For Mac OS X, the command is as follows (where SDKfolder is the path to your SDK location):

    export PATH=$PATH:/SDKfolder/cmake-#-#-#-Darwin-x86_64/CMake.app/Contents/bin/

For Linux, use

    export PATH=$PATH:/SDKfolder/cmake-#-#-#-Linux-x86_64/bin/

Typically, you would add this line, or a similar one for other shells, to your shell setup file. At the time of release 4.0, the correct cmake version number is 3.9.2.

Since this is the first time you build the package, you must create a Build folder. It is good practice to create this folder outside of the EMsoft source code folder. So, if the source code is installed in /Users/Me/Files/EMsoftPublic, then you would cd into the /Users/Me/Files folder and create the Build folder as:

	mkdir EMsoftBuild

You will also need a folder to keep all the data files that you will generate with the EMsoft package, so you can create a second folder for that:

	mkdir EMData

Next, you have two options; pick one or the other, depending on how you want to organize things:

1. If you only want to create a complete build of the package, and you are not going to develop additional code, then you should execute the following command inside the EMsoftBuild folder:

    cmake -DEMsoft_SDK=/SDKfolder -DCMAKE_BUILD_TYPE=Release ../EMsoftPublic
   

Note that these commands are case-sensitive, so pay attention to upper and lower-case characters! This command should be executed only the first time you build the package; it will initialize all the CMake files that are necessary to compile the libraries and programs. When the command has completed, then type:

	make -j#

where # is the number of cores you want to use for the compilation; if you type make -j12, then the compilation will be carried out on 12 cores, and if you omit the number (make -j), then the build will use as many cores as are available. The compilation process should complete without errors, and then you have a fully functional EMsoft package (check the EMsoft Configuration wiki page for information on what to do before you run the first program)

2. If you are going to develop code, then it might make more sense to generate both a Debug and a Release build folder. So, inside the EMsoftBuild folder, generate two additional folders and execute the following commands:

    mkdir Release
    mkdir Debug
    cd Release
    cmake -DEMsoft_SDK=/SDKfolder -DCMAKE_BUILD_TYPE=Release ../../EMsoftPublic
    make -j
    cd ../Debug
    cmake -DEMsoft_SDK=/SDKfolder -DCMAKE_BUILD_TYPE=Debug ../../EMsoftPublic
    make -j
   

After completion, you will have two versions of the executables, one in Release mode, the other in Debug mode.

Once your build process has completed, you can add the location of the Bin folder inside the Build folder to your PATH variable in the shell setup file, so that you can easily access all of the programs.