Configuring the Compilation
|Input||Testing and Monitoring|
|Include Files||Intermediate Files|
|Additional Build Libraries||Building for Different Systems|
|Compiler Settings||Setting the Compiler|
|Extra Object Files|
The CCompilerDriver package lets you work with C compilers that are installed on your computer. It lets you build executables, libraries, and object files from C source code. It is called automatically by the Wolfram System compiler when you set the option CompilationTarget to "C". It is also useful for building WSTP executables as well as Wolfram Libraries (dynamic linking libraries that can be linked into the Wolfram Language).
This section discusses the various controls the package provides for using a C compiler. Many of the examples will show creating a library, but the general principles also apply to creating an executable and an object file.
If you want to configure a C compiler when it is called automatically from the Wolfram System compiler you can use Compile`$CCompilerOptions.
The output is created in a folder automatically chosen by the Wolfram System. You can change the output folder with the "TargetDirectory" option. The automatic location is given by the variable $CCompilerDefaultDirectory.
The library is created in a folder automatically chosen by the Wolfram System. You can change the output folder with the "TargetDirectory" option. The automatic location is given by the variable $CCompilerDefaultDirectory.
This changes the location where the output is created; this will use the folder $BaseDirectory.
In addition to the settings from "IncludeDirectories", other locations are added by default. These include the locations of include files for Wolfram Libraries and for WSTP. The actual locations are set by the option "SystemIncludeDirectories".
This build command adds $UserBaseDirectory as an extra include directory.
|"IncludeDirectories"||add locations to the include path|
|"SystemIncludeDirectories"||default include locations (includes Wolfram Libraries and WSTP)|
"LibraryDirectories" adds extra locations to search for libraries and "Libraries" gives the names of the libraries. Both can take a single string or a list of strings. When you add the name of a library it will typically be its truncated name.
In addition to these settings, other locations and libraries are also added. These include settings so that WSTP libraries can be found. If you want to modify these standard settings you can use the options "SystemLibraryDirectories" and "SystemLibraries".
|"LibraryDirectories"||add locations to the library search path|
|"Libraries"||add libraries to include in the build|
|"SystemLibraryDirectories"||default library locations (includes WSTP)|
|"SystemLibraries"||default libraries (includes WSTP)|
The "CompileOptions" option adds compiler-specific flags; it can take a string or a list of strings. In addition to these, other default settings are also added; these are set by "SystemCompileOptions".
|"CompileOptions"||compiler-specific settings for the compilation|
|"SystemCompileOptions"||default compiler settings for the compilation|
|"Defines"||preprocessor defines to add to the compilation|
The CCompilerDriver package typically compiles and links code into an output library or executable. However, it also allows you to include extra object files in your build. This can be useful if you want to compile some files with different settings.
The example will use SymbolicC to create the sample code. First, the packages are loaded.
|"ShellOutputFunction"||function to display output of the compile process|
|"ShellCommandFunction"||function to display commands used in the compile process|
|"CreateBinary"||whether the compile process should actually execute|
You can use a debugger to inspect your code as it executes. This needs various special options to be set. You could use the "CompileOptions" option to set these, but the actual settings are different for each compiler. In addition, you might have to prevent intermediate files from being deleted with "CleanIntermediate".
You will need to delete the temporary files manually, noting the working directory name from the build output. In the example above, this working directory is C:\Users\jfklein\AppData\Roaming\Mathematica\SystemFiles\LibraryResources\Windows-x86-64\Working-xavier-i2win-4848-4428-16.
Compilation may create various intermediate files, but typically they are not needed and so are deleted at the end of compilation. There is also a decision about what constitutes an intermediate file. For example, when you build a dynamic library on Windows the build will create a DLL file, but also a stub LIB file and an export EXP file.
|True||clean all intermediate files|
|False||preserve all intermediate files|
|Automatic||clean all intermediate files, except the stub LIB file and export EXP file in Windows|
|Full||clean all files in the working directory, without regard to whether they are intermediate files or not|
This shows that the three files for the dynamic library on Windows are kept, a feature of the default setting of Automatic.
This runs the command but uses a "CleanIntermediate" of True.
This creates the library, but sets "CleanIntermediate" to False.
The "TargetSystemID" option allows some degree of control to create results for a specific system. The default setting is to create one compatible with the current version of the Wolfram Language. However, if your compiler can generate other types of output, you can use "TargetSystemID". It can be useful to create 32-bit results when running on a 64-bit machine.
When you use a compilation command such as CreateExecutable, it searches for a compiler that is available and suitable for your system. The details of how this is done are found in the section on Specific Compilers.
The option "Compiler" is used to set the type of compiler, such as Visual Studio or GCC. This might be useful if you have more than one compiler installed, or if the compiler you have is not detected automatically.
The option "CompilerInstallation" is used to set the location of the compiler software. Some compilers use environment variables to advertise their location and some are automatically found on a path. However, if your compiler cannot be found by one of these mechanisms you can use the option.
The option "CompilerName" is used to set the name of the compiler executable. This is useful if the compiler software supports more than one compiler command, for example, gcc can also be known as g++.
|"Compiler"||which compiler should be used|
|"CompilerInstallation"||the location of the compiler software|
|"CompilerName"||the name of the compile command to use|