Installation

Using a precompiled binary release

In order to use Azul from languages other than Rust you need to use a pre-compiled binary release from https://azul.rs/releases.

Even for Rust it is recommended to use the precompiled binary to avoid compilation issues (missing build-dependencies, long compilation time). The precompiled library is dependency-free, you do not need to install or extra system libraries in order to get started.

Python

In order to use Azul from Python, download the azul.pyd file (or azul.so on Linux / Mac) and put it in to the same directory as your main.py file. Note that because of Python extension conventions the name of the file must match the name of the library (i.e. azul.so instead of libazul.so).

Create a main.py file with the following contents:

from azul import *

Your project directory should now look like this:

/my-project: azul.pyd (or: azul.so) main.py

Now you should be able to run the code with

python ./main.py

C / C++

For C or C++ you will need to download the regular library without Python support:

•   Windows: azul.dll and azul.dll.lib

•   Linux: libazul.so

•   Mac: libazul.dylib

Create a main.c or main.cpp file with the following contents:

#include "azul.h" int main() { return 0; }

Your project directory should now look like this:

/my-project: azul.dll / libazul.so / libazul.dylib azul.dll.lib // windows only! azul.h / azul.hpp main.c / main.cpp

Compile with:

gcc -O3 -lazul -L/path/to/my-project ./main.c

Now you can run the example with

./main

Rust

Initialize a new cargo project with cargo new my-project and edit your Cargo.toml file:

[dependencies] azul = "1.0.0-alpha"

Run cargo with:

cargo build --release

This will throw an error because the compiler doesn't know where the azul.dll file is:

Compiling azul v0.0.1 error: environment variable `AZUL_LINK_PATH` not defined --> [...]\api\rust\build.rs:4:48 | 4 | println!("cargo:rustc-link-search={}", env!("AZUL_LINK_PATH")); | ^^^^^^^^^^^^^^^^^^^^^^ |

In order to tell rustc about the library, you will need to set the environment variable AZUL_LINK_PATH to the path of the downloaded library.

On Linux or Mac the operating system needs the library to be in the LD_PRELOAD path, so you can just AZUL_LINK_PATH to the same path:

sudo cp ./libazul.so /usr/lib export AZUL_LINK_PATH=/usr/lib cargo run --release

On Windows things are different: First, you will also need to put the azul.dll.lib file into the same directory as the azul.dllfile and second, in order to run the binary, the azul.dll file has to be in the same directory as the .exe.

For Rust development it makes the most sense to put both files into the /target/release directory:

/my-project /src main.rs /target /release my-project.exe azul.dll azul.dll.lib Cargo.toml SET AZUL_LINK_PATH=/path/to/my-project/target/release cargo run --release

Now your code should run (if it doesn't, file a bug). You can now continue with the next tutorial which will teach you how to create a window.

Static linking

C / C++

In order to link azul staticall from C or C++, apply the same procedure as for the dynamically linked version, but use the libazul.a file to link statically (as a single binary) instead of dynamically (as a split binary + azul.dll).

Rust

In order to link Rust as a regular crates.io dependency, you need to enable the link_static feature:

[dependencies] azul = { version = "1.0.0-alpha", features = ["link_static", "rlib"]}

By default this feature is disabled because re-linking the application can take a long time (even if compilation is fast). Usually you'd only want to do this when you are finished with the development of your application.

Building the library from source

Azul is mostly self-contained and using a default Rust installation you should be able to just compile it with:

git clone https://github.com/fschutt/azul cd azul-dll cargo build --release # --features="python3": optional Python support # --features="cdylib": compile as cdylib (.dll) # --features="staticlib": compile as static library (.a)

Development

Since Azul targets many languages, the bindings are auto-generated by a combination of a Python script (build.py) and a api.json file describing every class with the respective C field layout:

{ "App": { "external": "azul_impl::app::AzAppPtr", "doc": "Main application class", "struct_fields": [ {"ptr": {"type": "*const c_void"}} ], "constructors": { "new": { ... } }, ... }

The script then creates the proper API bindings. The API bindings only have to be refreshed when they are changed - which should happen infrequently.

Back to overview