Skip to main content

​
Building from Source

QuickJS uses CMake as its primary build system, with a convenient Makefile wrapper for Unix-like systems.
Windows users need to run CMake commands manually. See the Windows build instructions below.

​
Prerequisites

1

Install build tools

sudo apt-get update
sudo apt-get install build-essential cmake git
2

Clone the repository

git clone https://github.com/quickjs-ng/quickjs.git
cd quickjs

​
Standard Build

1

Build with Makefile (Linux/macOS)

The simplest way to build QuickJS:
make
This creates:
  • build/qjs - The QuickJS interpreter
  • build/qjsc - The QuickJS compiler
  • build/libquickjs.a - Static library
  • Additional test tools
2

Install system-wide

sudo make install
Default installation prefix is /usr/local. To customize:
make install INSTALL_PREFIX=/custom/path

​
Build Types

​
Debug Build

For development work with debug symbols and no optimizations: 
make debug
Or manually: 
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
Debug builds are essential for debugging with gdb or lldb. They include symbols and disable optimizations that can make debugging difficult.

​
Release Build

Optimized build for production (default): 
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

​
Shared Library Build

Build QuickJS as a shared library: 
cmake -B build -DBUILD_SHARED_LIBS=ON
cmake --build build

​
CMake Build Options

QuickJS supports several CMake options for customization:
OptionDescriptionDefault
BUILD_SHARED_LIBSBuild shared library instead of staticOFF
QJS_BUILD_WERRORBuild with -Werror (treat warnings as errors)OFF
QJS_BUILD_EXAMPLESBuild example programsOFF
QJS_BUILD_CLI_STATICBuild static qjs executableOFF
QJS_DISABLE_PARSERDisable JavaScript parserOFF
QJS_ENABLE_ASANEnable AddressSanitizerOFF
QJS_ENABLE_MSANEnable MemorySanitizerOFF
QJS_ENABLE_TSANEnable ThreadSanitizerOFF
QJS_ENABLE_UBSANEnable UndefinedBehaviorSanitizerOFF

​
Example: Build with Options

cmake -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=ON \
  -DQJS_BUILD_EXAMPLES=ON \
  -DQJS_ENABLE_UBSAN=ON
  
cmake --build build -j $(nproc)
Sanitizers (ASAN, MSAN, TSAN, UBSAN) are for testing only. Don’t use them in production builds as they significantly impact performance.

​
Platform-Specific Builds

​
Windows

1

Generate Visual Studio project

cmake -B build -G "Visual Studio 16 2019" -A x64
2

Build the project

cmake --build build --config Release
3

Run the binaries

.\build\Release\qjs.exe

​
MinGW on Windows

cmake -B build -G "MinGW Makefiles"
cmake --build build

​
Cross-Compilation

For ARM or other architectures, use a CMake toolchain file: 
cmake -B build -DCMAKE_TOOLCHAIN_FILE=path/to/toolchain.cmake
cmake --build build

​
Amalgamated Build

The amalgamated build combines all QuickJS source files into a single quickjs-amalgam.c file. This is ideal for embedding in projects without CMake.
1

Build QuickJS first

make
2

Generate amalgamated source

make amalgam
This creates build/quickjs-amalgam.zip containing:
  • quickjs-amalgam.c
  • quickjs.h
  • quickjs-libc.h
3

Use in your project

unzip build/quickjs-amalgam.zip
gcc -c quickjs-amalgam.c -DQJS_BUILD_LIBC -o quickjs.o
gcc your_app.c quickjs.o -lm -lpthread -o your_app
To enable the std, os, and bjson modules in amalgamated builds, compile with -DQJS_BUILD_LIBC.

​
Testing

​
Run Test262 Suite

Test QuickJS against the official ECMAScript test suite: 
make test262
This runs the test262 conformance tests.

​
Update Test Results

After implementing new features, update the test results: 
make test262-update
This regenerates the error/pass report based on current test results.

​
Advanced Build Options

​
Parallel Builds

Speed up compilation by using multiple CPU cores: 
# Using make
make -j$(nproc)

# Using CMake
cmake --build build -j $(nproc)

​
Custom Installation Prefix

cmake -B build -DCMAKE_INSTALL_PREFIX=/opt/quickjs
cmake --build build
cmake --install build

​
Static REPL Executable

Build a fully static qjs binary: 
cmake -B build -DQJS_BUILD_CLI_STATIC=ON
cmake --build build

​
Build with mimalloc

Use the mimalloc allocator for better performance: 
cmake -B build -DQJS_BUILD_CLI_WITH_MIMALLOC=ON
cmake --build build

​
Cleaning Build Artifacts

make clean

​
Verifying the Build

After building, verify everything works:
1

Test the interpreter

./build/qjs
# In the REPL:
qjs > console.log('Build successful!')
Build successful!
2

Test the compiler

echo 'console.log(42)' > test.js
./build/qjsc -o test.c test.js
gcc test.c -o test -lm -lpthread
./test
# Output: 42
3

Check statistics

make stats
This displays QuickJS internal statistics.

​
Troubleshooting

​
Build Fails with Missing Dependencies

Make sure you have all required tools: 
cmake --version  # Should be 3.10 or higher
gcc --version    # Or your C compiler
make --version

​
Linker Errors

Ensure you’re linking all required libraries: 
gcc your_app.c -lquickjs -lm -lpthread -o your_app

​
Permission Errors During Install

Use sudo for system-wide installation: 
sudo make install
Or install to a user directory: 
make install INSTALL_PREFIX=$HOME/.local

​
Next Steps

Quick Start

Start using your QuickJS build

API Reference

Learn the QuickJS C API

Examples

Explore code examples

Contributing

Contribute to QuickJS development

Build docs developers (and LLMs) love

Get started for freeTalk to us