## Preamble

Suppose you have written a file named logfunc.c containing an implementation of your mathematical objective function and a main.c file containing call(s) to the ParaMonte routines of your choice to sample the objective function.

The corresponding required logfunc.h and paramonte.h header files can be also downloaded from here and here.

If you have not made up your mind yet, we recommend using the prebuilt ParaMonte binaries. Although the entire ParaMonte library build process is fully automated, it can take much longer than simply downloading the prebuilt ParaMonte libraries from the project’s repository.

### Preamble: The compiler choice

• On Windows OS
• We recommend installing and using the Intel Parallel Studio 2019 or newer, although older versions may also work.

• Alternatively, you can also install and use a recent release of the Microsoft Visual C/C++ compiler (MSVC) 2019 or newer on your system. The community release of this compiler is free to the public and sufficient for many applications.

• On Linux OS
• We recommend installing and using the Intel Parallel Studio 2018 or newer, although older versions may also work.
• Alternatively, you can also install a recent release of the GNU Compiler Collection gcc/g++/gfortran (preferably version 9.1.0 or newer) instead of the Intel compiler suite. If you intend to build parallel applications, you will have to also have a compatible MPI library installed on your system, preferably the MPICH MPI library 3.2 or newer.
• On macOS
The situation is slightly complicated on MacOS. Apparently, Apple and Intel corporations have an intense internal rivalry and competition with each other, so much that Apple did not want to help Intel make their MPI library available on macOS. As a result, the Intel Parallel Studio cannot be used to build parallel MPI applications on macOS. Therefore,
• If you intend to build and use serial ParaMonte applications, then we still recommend installing and using the Intel Compiler Suite 2019 or newer on your system.
• If you intend to build and use parallel ParaMonte applications, then the best option would be to download and install a recent version of the GNU Compiler Collection (preferably, the same version with which the ParaMonte was built: 9.1.0) as well as the Open-MPI library 4.0.5.

### Preamble: Setting up the environment

In brief, the process of building your C application involves the following steps,

1. Either,
• Download the ParaMonte prebuilt library of your choice from the release page of the ParaMonte repository on GitHub. If you are not sure which one is suitable for your usage, see,
• or build the ParaMonte library for the configuration of your choice.
2. Navigate to the directory containing your uncompressed ParaMonte library files and paste (that is, overwrite the existing three paramonte.in, logfunc.c, and main.c files with) your files and codes.
3. Open a command-line interface and navigate to the directory containing your uncompressed ParaMonte library files.
• On Windows
• If you choose to use the Intel C compiler to build your application, then we strongly recommend you to use the Intel Parallel Studio’s customized command-line interface that is automatically installed on your system. You can access it from the Windows startup menu as illustrated in the figure below.

Open a 64-bit instance of the Intel Parallel Studio’s command-line interface. This command-line prompt comes with all the relevant compiler and linker environmental variables predefined in your session so that you won’t need to manually modify the contents of your environmental PATH variable.

• If you choose to use the MSVC C compiler cl, then we strongly recommend you to use the Microsoft Visual Studio’s customized command-line interface that is automatically installed on your system along with the compiler. It is normally named x64 Native Tools Command Prompt for VS 2XXX, where 2XXX is the version of the MSVC you have installed on your system. You can access it from the Windows startup menu as illustrated in the figure below, where the Microsoft Visual Studio 2019 is located (as well as an older existing installation of the Visual Studio 2017).

Open an instance of the x64 Native Tools Command Prompt which is automatically installed on your system along with the MSVC compiler. This command-line comes with all the relevant compiler and linker environmental variables predefined in your session so that you won’t need to manually modify the contents of the environmental PATH variable.

• On Linux / macOS, use a Bash terminal.

## Building the executable: The quick automated approach

• On Windows
• To build your application via the Intel C compiler, type the following on the Intel Parallel Studio command-line interface that you opened in the previous section,
build.bat

• To build your application via the Microsoft C compiler, type the following on the Microsoft Visual Studio command-line interface that you opened in the previous section,
build.bat msvc


The above Batch script will both build and run the application executable. See this page on how to set the number of processors for parallel simulations.

• On Linux / macOS
Type the following on the Bash terminal that you opened in the previous section,
chmod +x build.sh
./build.sh


The build-script generates the executable along with a Bash script run.sh in the same directory, which can be called on the command-line to run the executable. See this page on how to set the number of processors for parallel simulations and run the executable.

If your simulation-build and run have been successful, you can skip the following detailed sections on the build process via different specific compilers on different platforms and glance through the tips and information provided in the examples on this website to post-process the ParaMonte simulation results and output files.

## Building the executable: Do-it-yourself

There are currently more than 210 possible configurations with which you can build the ParaMonte library. Covering the compilation and linking procedure for all of these different scenarios here is impossible. To simplify, we will only consider compiling and linking your C application via the ParaMonte library build in release mode for only dynamic-linking. Before continuing to build your application manually, make sure you follow the guidelines outlined in the Preamble section in the above.

### Building the executable on Windows via the Intel C compiler

Depending on the build type you would like to specify for your application ( release, testing, debug ), you may want to define the compiler/linker flags,

• for release:
set "COMPILER_LINKER_FLAGS=/O3 /Qip /Qipo /Qunroll /Qunroll-aggressive /Ob2 /Qinline-dllimport"

• for testing:
set "COMPILER_LINKER_FLAGS=/Od"

• for debug:
set "COMPILER_LINKER_FLAGS=/debug:full /Zi /Od /Wall /traceback /Qcheck-pointers:rw /Qcheck-pointers-undimensioned /Qdiag-error-limit:10 /Qtrapuv"


#### Building the executable on Windows via the Intel C compiler for serial applications

• We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here.

• Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder,

dir /a /b /n

build.bat
libparamonte_c_windows_x64_intel_release_dynamic_heap.dll
libparamonte_c_windows_x64_intel_release_dynamic_heap.exp
libparamonte_c_windows_x64_intel_release_dynamic_heap.lib
logfunc.c
logfunc.h
main.c
paramonte.h
paramonte.in

• Now, we are going to use the Intel C compiler to compile and link your code,

set "COMPILER_LINKER_FLAGS=/O3 /Qip /Qipo /Qunroll /Qunroll-aggressive /Ob2 /Qinline-dllimport"

icl %COMPILER_LINKER_FLAGS% logfunc.c main.c libparamonte_c_windows_x64_intel_release_dynamic_heap.lib /link /out:main.exe

Intel(R) C++ Intel(R) 64 Compiler for applications running on Intel(R) 64, Version 19.0.4.245 Build 20190417

logfunc.c
main.c
Microsoft (R) Incremental Linker Version 14.22.27905.0

-out:main.exe
C:\Users\SHAHMO~1\AppData\Local\Temp\ipo_4826420.obj
libparamonte_c_windows_x64_intel_release_dynamic_heap.lib

• The above step should generate a main.exe executable file in the same directory. You can now run this executable to generate samples from your objective function as implemented in logfunc.c.

#### Building the executable on Windows via the Intel C compiler for parallel applications

• For simplicity, we will only consider the MPI-parallelism here. We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here.

• Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder,

dir /a /b /n

build.bat
libparamonte_c_windows_x64_intel_release_dynamic_heap_mpi.dll
libparamonte_c_windows_x64_intel_release_dynamic_heap_mpi.exp
libparamonte_c_windows_x64_intel_release_dynamic_heap_mpi.lib
logfunc.c
logfunc.h
main.c
paramonte.h
paramonte.in

• Now, we are going to use the Intel C MPI compiler wrapper to compile and link your code,

set "COMPILER_LINKER_FLAGS=/O3 /Qip /Qipo /Qunroll /Qunroll-aggressive /Ob2 /Qinline-dllimport"

mpiicc %COMPILER_LINKER_FLAGS% logfunc.c main.c libparamonte_c_windows_x64_intel_release_dynamic_heap_mpi.lib /link /out:main.exe

mpicc.bat for the Intel(R) MPI Library 2019 Update 4 for Windows*

Intel(R) C++ Intel(R) 64 Compiler for applications running on Intel(R) 64, Version 19.0.4.245 Build 20190417

logfunc.c
main.c
Microsoft (R) Incremental Linker Version 14.22.27905.0

-out:main.exe
"/LIBPATH:C:\Program Files (x86)\IntelSWTools\compilers_and_libraries_2019.4.245\windows\mpi\intel64\bin\..\..\intel64\lib\release"
"/LIBPATH:C:\Program Files (x86)\IntelSWTools\compilers_and_libraries_2019.4.245\windows\mpi\intel64\bin\..\..\intel64\lib"
impi.lib
impicxx.lib
C:\Users\SHAHMO~1\AppData\Local\Temp\ipo_4049220.obj
libparamonte_c_windows_x64_intel_release_dynamic_heap_mpi.lib

• The above step should generate an MPI-parallelized main.exe executable file in the same directory. You can now run this executable – in parallel on any number of processors you wish – to generate samples from your objective function as implemented in logfunc.c.

### Building the executable on Windows via the Microsoft Visual C compiler

Open an instance of the x64 Native Tools Command Prompt which is automatically installed on your system along with the MSVC compiler. As discussed in the preamble, this command-line comes with all the relevant compiler and linker environmental variables predefined in your session so that you won’t need to manually modify the contents of the environmental PATH variable.

Depending on the build type you would like to specify for your application ( release, testing, debug ), you may want to define the compiler/linker flags,

• for release:
set "COMPILER_LINKER_FLAGS=/O2"

• for testing:
set "COMPILER_LINKER_FLAGS=/Od"

• for debug:
set "COMPILER_LINKER_FLAGS=/Od /Z7"


#### Building the executable on Windows via the Microsoft Visual C compiler for serial applications

• We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here.

• Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder,

dir /a /b /n

build.bat
libparamonte_c_windows_x64_msvc_release_dynamic_heap.dll
libparamonte_c_windows_x64_msvc_release_dynamic_heap.exp
libparamonte_c_windows_x64_msvc_release_dynamic_heap.lib
logfunc.c
logfunc.h
main.c
paramonte.h
paramonte.in

• Now, we are going to use the MSVC C compiler cl to compile and link your code,
set "COMPILER_LINKER_FLAGS=/O2"

cl %COMPILER_LINKER_FLAGS% logfunc.c main.c libparamonte_c_windows_x64_intel_release_dynamic_heap.lib /link /out:main.exe

Microsoft (R) C/C++ Optimizing Compiler Version 19.22.27905 for x64

logfunc.c
main.c
Generating Code...
Microsoft (R) Incremental Linker Version 14.22.27905.0

/out:logfunc.exe
/out:main.exe
logfunc.obj
main.obj
libparamonte_c_windows_x64_intel_release_dynamic_heap.lib

• The above step should generate a main.exe executable file in the same directory. You can now run this executable to generate samples from your objective function as implemented in logfunc.c.

#### Building the executable on Windows via the Microsoft Visual C compiler for parallel applications

• For simplicity, we will only consider the MPI-parallelism here. We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here.

• Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder,

dir /a /b /n

build.bat
libparamonte_c_windows_x64_intel_release_dynamic_heap_mpi.dll
libparamonte_c_windows_x64_intel_release_dynamic_heap_mpi.exp
libparamonte_c_windows_x64_intel_release_dynamic_heap_mpi.lib
logfunc.c
logfunc.h
main.c
paramonte.h
paramonte.in

• Now, we are going to use the Intel mpicc or mpicl C MPI compiler wrappers along with the Microsoft C compiler cl.exe (specified by the flag -cc=cl) to compile and link your code,
set "COMPILER_LINKER_FLAGS=/O2"

mpicc -cc=cl %COMPILER_LINKER_FLAGS% logfunc.c main.c libparamonte_c_windows_x64_intel_release_dynamic_heap_mpi.lib /link /out:main.exe

mpicc.bat for the Intel(R) MPI Library 2019 Update 4 for Windows*

Microsoft (R) C/C++ Optimizing Compiler Version 19.22.27905 for x64

logfunc.c
main.c
Generating Code...
Microsoft (R) Incremental Linker Version 14.22.27905.0

/out:logfunc.exe
"/LIBPATH:C:\Program Files (x86)\IntelSWTools\compilers_and_libraries_2019.4.245\windows\mpi\intel64\bin\..\..\intel64\lib\release"
"/LIBPATH:C:\Program Files (x86)\IntelSWTools\compilers_and_libraries_2019.4.245\windows\mpi\intel64\bin\..\..\intel64\lib"
-out:main.exe
impi.lib
impicxx.lib
logfunc.obj
main.obj
libparamonte_c_windows_x64_intel_release_dynamic_heap_mpi.lib

• The above step should generate an MPI-parallelized main.exe executable file in the same directory. You can now run this executable – in parallel on any number of processors you wish – to generate samples from your objective function as implemented in logfunc.c.

### Building the executable on macOS via the Intel C compiler

Open a Bash terminal that recognizes your local installation of the Intel compilers and libraries.

Depending on the build type you would like to specify for your application ( release, testing, debug ), you may want to define the compiler/linker flags,

• for release:
export COMPILER_LINKER_FLAGS="-no-multibyte-chars -O3"

• for testing:
export COMPILER_LINKER_FLAGS="-no-multibyte-chars -O0"

• for debug:
export COMPILER_LINKER_FLAGS="-no-multibyte-chars -O0 -debug full"


To understand the reason for adding the compiler flag -no-multibyte-chars on macOS, see this troubleshooting page

#### Building the executable on macOS via the Intel C compiler for serial applications

• We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here.
• Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder,

ls -1

build.sh
libparamonte_c_darwin_x64_intel_release_dynamic_heap.dylib
logfunc.c
logfunc.h
main.c
paramonte.h
paramonte.in

• Now, we are going to use the Intel C compiler to compile and link your code,

export COMPILER_LINKER_FLAGS="-no-multibyte-chars -O3"

icc $COMPILER_LINKER_FLAGS logfunc.c main.c libparamonte_c_darwin_x64_intel_release_dynamic_heap.dylib -o main.exe  • The above step should generate a main.exe executable file in the same directory. You can now run this executable to generate samples from your objective function as implemented in logfunc.c. ### Building the executable on macOS via the GNU C compiler Open a Bash terminal that recognizes your local installation of the GNU compilers and libraries. Depending on the build type you would like to specify for your application ( release, testing, debug ), you may want to define the compiler/linker flags, • for release: export COMPILER_LINKER_FLAGS="-O3"  • for testing: export COMPILER_LINKER_FLAGS="-O0"  • for debug: export COMPILER_LINKER_FLAGS="-O0 -g"  #### Building the executable on macOS via the GNU C compiler for serial applications • We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here. • Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder, ls -1  build.sh libparamonte_c_darwin_x64_gnu_release_dynamic_heap.dylib logfunc.c logfunc.h main.c paramonte.h paramonte.in README.md  • Now, we are going to use the GNU C compiler to compile and link your code, export COMPILER_LINKER_FLAGS="-O3"  gcc$COMPILER_LINKER_FLAGS  logfunc.c main.c libparamonte_c_darwin_x64_gnu_release_dynamic_heap.dylib -o main.exe

• The above step should generate a main.exe executable file in the same directory. You can now run this executable to generate samples from your objective function as implemented in logfunc.c.

#### Building the executable on macOS via the GNU C compiler for MPI-parallel applications

• We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here.
• Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder,

ls -1

build.sh
libparamonte_c_darwin_x64_gnu_release_dynamic_heap_mpi.dylib
logfunc.c
logfunc.h
main.c
paramonte.h
paramonte.in

• Now, we are going to use the Open-MPI compiler wrapper for the GNU C compiler to compile and link your code,

export COMPILER_LINKER_FLAGS="-O3"

mpicc $COMPILER_LINKER_FLAGS logfunc.c main.c libparamonte_c_darwin_x64_gnu_release_dynamic_heap_mpi.dylib -o main.exe  • The above step should generate an MPI-parallelized main.exe executable file in the same directory. You can now run this executable – in parallel on any number of processors you wish – to generate samples from your objective function as implemented in logfunc.c. ### Building the executable on Linux via the Intel C compiler Open a Bash terminal that recognizes your local installation of the Intel compilers and libraries. Depending on the build type you would like to specify for your application ( release, testing, debug ), you may want to define the compiler/linker flags, • for release: export COMPILER_LINKER_FLAGS="-O3"  • for testing: export COMPILER_LINKER_FLAGS="-O0"  • for debug: export COMPILER_LINKER_FLAGS="-O0 -debug full"  #### Building the executable on Linux via the Intel C compiler for serial applications • We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here. • Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder, ls -1  build.sh libparamonte_c_linux_x64_intel_release_dynamic_heap.so logfunc.c logfunc.h main.c paramonte.h paramonte.in README.md  • Now, we are going to use the Intel C compiler to compile and link your code, export COMPILER_LINKER_FLAGS="-O3"  icc$COMPILER_LINKER_FLAGS  logfunc.c main.c libparamonte_c_linux_x64_intel_release_dynamic_heap.so -o main.exe

• The above step should generate a main.exe executable file in the same directory. You can now run this executable to generate samples from your objective function as implemented in logfunc.c.

#### Building the executable on Linux via the Intel C compiler for MPI-parallel applications

• We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here.
• Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder,

ls -1

build.sh
libparamonte_c_linux_x64_intel_release_dynamic_heap_mpi.so
logfunc.c
logfunc.h
main.c
paramonte.h
paramonte.in

• Now, we are going to use the Intel MPI compiler wrapper for the Intel C compiler to compile and link your code,

export COMPILER_LINKER_FLAGS="-O3"

mpiicc $COMPILER_LINKER_FLAGS logfunc.c main.c libparamonte_c_linux_x64_intel_release_dynamic_heap_mpi.so -o main.exe  • The above step should generate an MPI-parallelized main.exe executable file in the same directory. You can now run this executable – in parallel on any number of processors you wish – to generate samples from your objective function as implemented in logfunc.c. ### Building the executable on Linux via the GNU C compiler Open a Bash terminal that recognizes your local installation of the GNU compilers and libraries. Depending on the build type you would like to specify for your application ( release, testing, debug ), you may want to define the compiler/linker flags, • for release: export COMPILER_LINKER_FLAGS="-O3"  • for testing: export COMPILER_LINKER_FLAGS="-O0"  • for debug: export COMPILER_LINKER_FLAGS="-O0 -g"  #### Building the executable on Linux via the GNU C compiler for serial applications • We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here. • Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder, ls -1  build.sh libparamonte_c_linux_x64_gnu_release_dynamic_heap.so logfunc.c logfunc.h main.c paramonte.h paramonte.in README.md  • Now, we are going to use the GNU C compiler to compile and link your code, export COMPILER_LINKER_FLAGS="-O3"  gcc$COMPILER_LINKER_FLAGS  logfunc.c main.c libparamonte_c_linux_x64_gnu_release_dynamic_heap.so -o main.exe

• The above step should generate a main.exe executable file in the same directory. You can now run this executable to generate samples from your objective function as implemented in logfunc.c.

#### Building the executable on Linux via the GNU C compiler for MPI-parallel applications

• We will consider building the C application via the ParaMonte library build in release mode for dynamic-linking. The corresponding prebuilt ParaMonte library can be downloaded from here.
• Navigate to the folder containing the ParaMonte library on your local system. Move your C example codes to this folder (This will overwrite the existing logfunc.c and main.c files in this folder with yours). You should then be able to see the following files inside the folder,

ls -1

build.sh
libparamonte_c_linux_x64_gnu_release_dynamic_heap_mpi.so
logfunc.c
logfunc.h
main.c
paramonte.h
paramonte.in

export COMPILER_LINKER_FLAGS="-O3"

mpicc \$COMPILER_LINKER_FLAGS  logfunc.c main.c libparamonte_c_linux_x64_gnu_release_dynamic_heap_mpi.so -o main.exe

• The above step should generate an MPI-parallelized main.exe executable file in the same directory. You can now run this executable – in parallel on any number of processors you wish – to generate samples from your objective function as implemented in logfunc.c.