Build Instructions

Build instructions, supported environments, and feature selection.

Overview

AsmJit is designed to be easy embeddable in any project. However, it depends on some compile-time definitions that can be used to enable or disable features to decrease the resulting binary size. A typical way of building AsmJit is to use cmake, but it's also possible to just include AsmJit source code in your project and to just build it. The easiest way to include AsmJit in your project is to just include src directory in your project and to define ASMJIT_STATIC. AsmJit can be just updated from time to time without any changes to this integration process. Do not embed AsmJit's test files in such case as these are used exclusively for testing.

Supported C++ Compilers

  • Requirements:
    • AsmJit won't build without C++11 enabled. If you use older GCC or Clang you would have to enable at least C++11 standard through compiler flags.
  • Tested:
    • Clang - Tested by GitHub Actions - Clang 10+ is officially supported and tested by CI, older Clang versions having C++11 should work, but are not tested anymore due to upgraded CI images.
    • GNU - Tested by GitHub Actions - GCC 7+ is officially supported, older GCC versions from 4.8+ having C++11 enabled should also work, but are not tested anymore due to upgraded CI images.
    • MINGW - Reported to work, but not tested in our CI environment (help welcome).
    • MSVC - Tested by GitHub Actions - VS2019+ is officially supported, VS2015 and VS2017 is reported to work, but not tested by CI anymore.

Supported Operating Systems and Platforms

  • Tested:
    • BSD - FreeBSD, NetBSD, and OpenBSD tested by GitHub Actions (only recent images are tested by CI). BSD runners only test BSD images with clang compiler.
    • Linux - Tested by GitHub Actions (only recent Ubuntu images are tested by CI, in general any distribution should be supported as AsmJit has no dependencies).
    • Mac OS - Tested by GitHub Actions.
    • Windows - Tested by GitHub Actions - (Windows 7+ is officially supported).
    • Emscripten - Works if compiled with ASMJIT_NO_JIT. AsmJit cannot generate WASM code, but can be used to generate X86/X64/AArch64 code within a browser, for example.
  • Untested:

Supported Backends / Architectures

  • X86 and X86_64 - Both 32-bit and 64-bit backends tested on CI.
  • AArch64 - AArch64 backend is currently only partially tested (there is no native AArch64 runner to test AsmJit Builder/Compiler).

Static Builds and Embedding

These definitions can be used to enable static library build. Embed is used when AsmJit's source code is embedded directly in another project, implies static build as well.

Note
Projects that use AsmJit statically must define ASMJIT_STATIC in all compilation units that use AsmJit, otherwise AsmJit would use dynamic library imports in ASMJIT_API decorator. The recommendation is to define this macro across the whole project that uses AsmJit this way.

Build Configuration

These definitions control whether asserts are active or not. By default AsmJit would autodetect build configuration from existing pre-processor definitions, but this behavior can be overridden, for example to enable debug asserts in release configuration.

  • ASMJIT_BUILD_DEBUG - Overrides build configuration to debug, asserts will be enabled in this case.
  • ASMJIT_BUILD_RELEASE - Overrides build configuration to release, asserts will be disabled in this case.
Note
There is usually no need to override the build configuration. AsmJit detects the build configuration by checking whether NDEBUG is defined and automatically defines ASMJIT_BUILD_RELEASE if configuration overrides were not used. We only recommend using build configuration overrides in special situations, like using AsmJit in release configuration with asserts enabled for whatever reason.

AsmJit Backends

AsmJit currently supports only X86/X64 backend, but the plan is to add more backends in the future. By default AsmJit builds only the host backend, which is auto-detected at compile-time, but this can be overridden.

AsmJit Compilation Options

  • ASMJIT_NO_DEPRECATED - Disables deprecated API at compile time so it won't be available and the compilation will fail if there is attempt to use such API. This includes deprecated classes, namespaces, enumerations, and functions.
  • ASMJIT_NO_SHM_OPEN - Disables functionality that uses shm_open().
  • ASMJIT_NO_ABI_NAMESPACE - Disables inline ABI namespace within asmjit namespace. This is only provided for users that control all the dependencies (even transitive ones) and that make sure that no two AsmJit versions are used at the same time. This option can be debugging a little simpler as there would not be ABI tag after asmjit:: namespace. Otherwise asmjit would look like asmjit::_abi_1_13::, for example.

Features Selection

AsmJit builds by defaults all supported features, which includes all emitters, logging, instruction validation and introspection, and JIT memory allocation. Features can be disabled at compile time by using ASMJIT_NO_... definitions.

Note
It's not recommended to disable features if you plan to build AsmJit as a shared library that will be used by multiple projects that you don't control how AsmJit was built (for example AsmJit in a Linux distribution). The possibility to disable certain features exists mainly for customized AsmJit builds.

Macros

Macro Definition Documentation

#define ASMJIT_EMBED◆ 

Asmjit is embedded, implies ASMJIT_STATIC.

#define ASMJIT_STATIC◆ 

Enables static-library build.

#define ASMJIT_BUILD_DEBUG[1/2]◆ 

Defined when AsmJit's build configuration is 'Debug'.

Note
Can be defined explicitly to bypass auto-detection.

#define ASMJIT_BUILD_DEBUG[2/2]◆ 

Defined when AsmJit's build configuration is 'Debug'.

Note
Can be defined explicitly to bypass auto-detection.

#define ASMJIT_BUILD_RELEASE◆ 

Defined when AsmJit's build configuration is 'Release'.

Note
Can be defined explicitly to bypass auto-detection.

#define ASMJIT_NO_X86◆ 

Disables X86/X64 backends.

#define ASMJIT_NO_AARCH64◆ 

Disables AArch64 backend.

#define ASMJIT_NO_FOREIGN◆ 

Disables non-host backends entirely (useful for JIT compilers to minimize the library size).

#define ASMJIT_NO_DEPRECATED◆ 

Disables deprecated API at compile time (deprecated API won't be available).

#define ASMJIT_NO_BUILDER◆ 

Disables Builder functionality completely.

#define ASMJIT_NO_COMPILER◆ 

Disables Compiler functionality completely.

#define ASMJIT_NO_JIT◆ 

Disables JIT memory management and asmjit::JitRuntime.

#define ASMJIT_NO_LOGGING◆ 

#define ASMJIT_NO_TEXT◆ 

Disables everything that contains text.

#define ASMJIT_NO_VALIDATION◆ 

Disables instruction validation API.

#define ASMJIT_NO_INTROSPECTION◆ 

Disables instruction introspection API.