How to create a DLL from a Julia module

This document provides instructions on how to copmpile a Julia module to a library. It only covers Windows and might be outdated.
For the most recent version, other OSes and UI programs please have a look at the Wiki. You can also edit the Wiki directly to add info or fix issues.

In this file you find all commands that appear in this document so that you can copy and paste them to the Julia REPL and the command line avoid typing mistakes.

Package creation

Julia's PackageCompiler coompiles packages, as its names says. To compile a module as a library, you therefore first have to put it in a package.

1. Start the Julia REPL and execute this command to see if the package PackageCompiler is installed:
   using PackageCompiler
   if not, install it by first pressing the ']' key to get to package mode, then execute
   add PackageCompiler
2. Change there into the folder where the package should be created. For example of the package should be created in the folder D:\Julia execute this command
   cd("D:\\Julia")
3. Press ']' to enter Julia's package mode
4. The package should in our case have the name "Juliastic". Therefore execute now the command
   generate Juliastic
5. Close the Julia REPL

This created the folder D:\Julia\Juliastic and in the folder a file Project.toml and a subfolder src. Now you can fill in the code:

1. Open the file Project.toml with a text editor and change your name and the version number as you like.
2. Inside the src folder open the file Juliastic.jl with an editor of your choice.
3. Delete its content and paste in the code of your module.
4. Create in D:\Julia\Juliastic a subfolder named build (the name is important, so it must have the name "build").

Definition of the library header

1. In the build folder create the file Juliastic.h (the name must be the name of the module, so it must have the name "Juliastic")
2. Edit Juliastic.h with an editor of your choice so that it defines a function header in the syntax of the programming language C for every exported function of the Julia module. See the file Juliastic.h of this repository as example.

Registering dependencies

Most Julia programs call packages. If you module does this too via the using statement, you must add these packages to the dependency of the package.

1. Open Julia's REPL
2. Start the Julia REPL and change there to the Juliastic folder. In our case execute:
   cd("D:\\Julia\\Juliastic)
   to change to that folder
3. Press ']' to enter Julia's package mode
4. Execute the command
   activate .
   (note the dot in the command)
5. You can now packages that are needed for your module one after another. For example to add the package Distributions, execute this command:
   add --preserve=direct Distributions
   (the command option --preserve preserves the version of packages at what Distributions directly depend on, see the docs if you want more information)
6. If necessary add more packages. Finally close the Julia REPL.

Preparing the compilation (precompilation)

Since Julia uses a just-in-time compiler (JIT), it is recommended to compile the Julia module before the library is compiled. This process is called "precompilation". The prcompilation is done by simply calling all functions of the module in a Julia script.

1. Create a Julia script in the build folder, named e.g. "precompilation.jl". In that file call all functions as you designed them.

The precompilation also assures that all functions are working. Julia will issue errors if not. Since the JIT creates optimal code after several consecutive executions, you can as a "trick" to call every function e.g. 10 times in a while loop. See the file precompilation.jl of this repository for an example.

Compilation of the library

1. Start Julia's REPL.
2. Change in Julia to the Juliastic folder. In our case execute these two commands subsequently:

   lib_input_path= "D:\\Julia\\Juliastic"  
   cd(lib_input_path)
   

   to change to that folder
3. now execute this command sequence:
   (for detailed info of the create_library command, see its documentation)

   using PackageCompiler  
   lib_name= "Juliastic"  
   lib_output= joinpath(lib_input_path, "CompilationResult")  
   precomp_file= joinpath(lib_input_path, "build", "precompilation.jl")  
   lib_header= joinpath(lib_input_path, "build", lib_name * ".h")  
   create_library(lib_input_path, lib_output;  
    incremental= false, force= true, filter_stdlibs= true, lib_name= lib_name,  
    precompile_execution_file= precomp_file,  
    header_files= [lib_header])
   

This can take several minutes. There might be messages that some threads could not be ended. You can ignore them as they appear no matter what thread settings you have for Julia and Julia waits automatically long enough to close the thread after a while. Important is that you eventually see this message in the REPL:
[ Info: PackageCompiler: Done
and after some more seconds the Julia REPL prompt "julia>".

Testing the library

The library is callable from any program that can handle libraries compiled for the programming language C. To test the library, we compile a simple C program. In this repository you find a small C program in the file DLLTestProgram.c. Copy it to the folder D:\Julia\Juliastic then edit it with an editor of your choice according to your module definitions. Important is thereby that you change "Juliastic" the line
#include "CompilationResult\include\Juliastic.h"
to your module name.

1. Install the Mingw-w64 compiler. Use thereby all default settings in the installation process.
2. Open a command line (run the cmd.exe) and change there to the path of the library by executing in our case the commands
   d:
   then
   cd D:\\Julia\\Juliastic
3. Test if the compiler is properly installed by executing
   gcc --version
4. If you did not get an error message, you can now compile the program by executing this command:
   gcc DLLTestProgram.c -o CompilationResult\\bin\\DLLTestProgram.exe -ICompilationResult\\include -LCompilationResult\\bin -ljulia -lJuliastic
   (replace thereby at the end "Juliastic" with your module name)

We don't go to the details of that gcc call. Important is that you did not get any errors and that you keep the command line open.

You should now have the file DLLTestProgram.exe in the folder D:\Julia\Juliastic\CompilationResult\bin.

Note: It is important that executables using the library must be in the same folder where PackageCompiler put in all necessary libraries to run Julia. This is the folder bin. Julia expects the folder share in the same folder than bin, therefore you cannot go the other way and copy all Julia libraries from the bin folder to the folder of DLLTestProgram.exe.

1. In the command line change to D:\Julia\Juliastic\CompilationResult\bin by executing
   cd D:\\Julia\\Juliastic\\CompilationResult\\bin
2. Execute now
   DLLTestProgram

As result you should get some output according to the "printf" commands in the DLLTestProgram.c.

If that is the case, congratulations!
You mastered a long journey.

To use your library for e.g. UI programs, you have to follow specific steps defined by these programs. If you are interested in this, we demonstarte this in the following at an example:

Excursus: How to use a Julia library for Lazarus UI programs

In the following we demonstrate how the library is used in the platform-independent UI program Lazarus. Lazarus can generate UI programs on all major OSes and because its license gives flexibility also for commercial applications. However, we strongly recommend to provide your code as OpenSource, also if you have commercial applications. You already benefit from OpenSource and a proper business model should include OpenSource.

Creation of a UI program

1. If not already installed, install Lazarus in the 64 bit version (not the mixed 32/64 bit version). 64 bit is important because Julia DLLs are 64 bit. If you have an old Lazarus installation, better uninstall it and reinstall the latest Lazarus release.
2. Copy the folder LazarusExample of this repository to the folder D:\Julia\Juliastic.

Like for the C program we used for testing, Lazarus will only properly work if the Lazarus executable will be created in the folder where Julia created the file Juliastic.dll. Therefore you must set the output path of the executable to that folder:

1. Go to the folder D:\Julia\Juliastic\LazarusExample and double-click on the file DLLTest.lpi to start Lazarus.
2. Go to the menu Project -> Project Options. Navigate there to the Compiler Options section.
3. There in the field Target file name (-o) set
   ..\\CompilationResult\\bin\\DLLTest
   and press OK.

(In principle Lazarus allows you to call a DLL from any path, however, Juliastic.dll is connected to other Julia DLLs. Therefore if you or a user runs the final executable on a computer where Julia is in a PATH environment variable of Windows, the DLL might not be loaded since then different DLL versions can internally be mixed.)

Note: The Lazarus project files must not be in D:\Julia\Juliastic\CompilationResult\bin because this folder is deleted every time you recompile your DLL.

1. Compile and run your program with Lazarus.

Debugging

To debug your program with Lazarus, the default debugger FpDebug cannot be used. It will hang up as soon as the DLL is invoked. Use instead the GNU debugger:

1. Go to the menu Project -> Project Options. Navigate there to the Debugger section.
2. There in the field Debugger Backend select Gdb [GNU debugger] and press OK.

Distributing

In order that users can use your program, you have to distrbute several libraries with your executable. This is done by creating a ZIP file:

1. ZIP the complete folder CompilationResult
2. Open the ZIP and first change there the folder name from "CompilationResult" to the name of your program, for example to "DLLTest".
3. Optional: in the ZIP file you can delete the subfolder include since these files are not needed by the user.

The user does not have to install or download Julia. with the distribution all necessary files will be available.

Congratulations!
You enabled your amazing Julia code to be used in a UI program so that your users don't have to deal with bare code.

The amount of files and their sizes you have to supply with your program is rather big but his might be reduced in future versions of Julia.