Index ⭢ Build Instructions

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 Operating Systems, Compilers, and Build Tools [¶]

Supported C++ Compilers

Requirements:
- AsmJit won't build without C++17 enabled. If you use older GCC or Clang you would have to enable at least C++17 standard through compiler flags.
Tested:
- Clang - Tested by GitHub Actions - Clang 14+ is officially supported and tested by CI, older Clang versions having C++17 should work, but these versions are not tested anymore due to upgraded CI images.
- GNU - Tested by GitHub Actions - GCC 9+ is officially supported and tested by CI, older GCC versions such as GCC 7 should work, but these versions 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 - VS2022 and onwards are officially supported and tested by CI, VS2015, VS2017, and VS2019 are not tested anymore due to upgraded CI images. VS2019 should work well.

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. Both X86_64 and AArch64 host builds are tested.
- 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). Linux tests X86, X86_64, and AArch64 host builds.
- 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:
- Haiku - Reported to work, not tested by CI.
- Other operating systems would require some testing and support in the following files:

Supported Backends / Architectures

X86 and X86_64 - Both 32-bit and 64-bit backends tested on CI.
AArch64 - Tested on CI (Native Apple runners and Linux emulated via QEMU).

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.

ASMJIT_EMBED - Asmjit is embedded, implies ASMJIT_STATIC.
ASMJIT_STATIC - Enable static-library build.

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.

CMake Integration [¶]

AsmJit has a first-class CMake support. When consuming AsmJit as a cmake dependency, just use asmjit::asmjit as a link dependency, which would instrument cmake to setup everything else, including include paths, and build flags (either defining ASMJIT_STATIC or not, and possibly defining other AsmJit feature macros). For example considering that AsmJit was fetched to 3rdparty/asmjit directory in your project as an external dependency, you can just use the following CMake snippet that integrates AsmJit with your own CMake project:

cmake_minimum_required(VERSION 3.30)
 
project(asmjit_consumer C CXX)    # Both C and CXX are required.
set(CMAKE_CXX_STANDARD 17)        # C++17 and never is supported.
 
set(ASMJIT_DIR "3rdparty/asmjit") # Location of AsmJit.
set(ASMJIT_STATIC TRUE)           # Force static build.
 
add_subdirectory("${ASMJIT_DIR}") # This adds AsmJit as a part of your project.
 
add_executable(asmjit_consumer asmjit_consumer.cpp)
target_link_libraries(
  asmjit_consumer asmjit::asmjit) # This adds AsmJit as a dependency to your target.

Build Type 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 [¶]

All backends AsmJit supports are included by default. To exclude a backend use the following build-type macros:

ASMJIT_NO_X86 - Disables both X86 and X86_64 backends.
ASMJIT_NO_AARCH64 - Disables AArch64 backend.
ASMJIT_NO_FOREIGN - Disables the support for foreign architecture backends, only keeps a native backend. For example if your target is X86, ASMJIT_NO_FOREIGN would disable every backend but X86.

Build 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.

Build Features [¶]

AsmJit builds by default 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.

ASMJIT_NO_JIT - Disables JIT memory management and JitRuntime.
ASMJIT_NO_TEXT - Disables everything that contains string representation of AsmJit constants, should be used together with ASMJIT_NO_LOGGING as logging doesn't make sense without the ability to query instruction names, register names, etc...
ASMJIT_NO_LOGGING - Disables Logger and Formatter.
ASMJIT_NO_VALIDATION - Disables validation API.
ASMJIT_NO_INTROSPECTION - Disables instruction introspection API, must be used together with ASMJIT_NO_COMPILER as Compiler requires introspection for its liveness analysis and register allocation.
ASMJIT_NO_BUILDER - Disables Builder functionality completely. This implies ASMJIT_NO_COMPILER as Compiler cannot be used without Builder.
ASMJIT_NO_COMPILER - Disables Compiler functionality completely.

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.