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:
  • Haiku - Reported to work, not tested by CI.
  • Other operating systems would require some testing and support in the following files:
    • core/api-config.h
    • core/osutils.cpp
    • core/virtmem.cpp

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.

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

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.

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

Macros

#define ASMJIT_EMBED

#define ASMJIT_STATIC

#define ASMJIT_BUILD_DEBUG

#define ASMJIT_BUILD_DEBUG

#define ASMJIT_BUILD_RELEASE

#define ASMJIT_NO_X86

#define ASMJIT_NO_AARCH64

#define ASMJIT_NO_FOREIGN

#define ASMJIT_NO_DEPRECATED

#define ASMJIT_NO_BUILDER

#define ASMJIT_NO_COMPILER

#define ASMJIT_NO_JIT

#define ASMJIT_NO_LOGGING

#define ASMJIT_NO_TEXT

#define ASMJIT_NO_VALIDATION

#define ASMJIT_NO_INTROSPECTION

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

Disables asmjit::Logger and asmjit::Formatter.

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