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

Install build tools

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

sudo dnf install gcc cmake make git

# Install Xcode Command Line Tools
xcode-select --install

# Install CMake (using Homebrew)
brew install cmake

# Install Visual Studio 2017 or later with C++ tools
# Install CMake from https://cmake.org/download/
# Install Git from https://git-scm.com/download/win

Clone the repository

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

Standard Build

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

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:

Option	Description	Default
`BUILD_SHARED_LIBS`	Build shared library instead of static	`OFF`
`QJS_BUILD_WERROR`	Build with -Werror (treat warnings as errors)	`OFF`
`QJS_BUILD_EXAMPLES`	Build example programs	`OFF`
`QJS_BUILD_CLI_STATIC`	Build static qjs executable	`OFF`
`QJS_DISABLE_PARSER`	Disable JavaScript parser	`OFF`
`QJS_ENABLE_ASAN`	Enable AddressSanitizer	`OFF`
`QJS_ENABLE_MSAN`	Enable MemorySanitizer	`OFF`
`QJS_ENABLE_TSAN`	Enable ThreadSanitizer	`OFF`
`QJS_ENABLE_UBSAN`	Enable UndefinedBehaviorSanitizer	`OFF`

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

Generate Visual Studio project

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

Build the project

cmake --build build --config Release

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.

Build QuickJS first

make

Generate amalgamated source

make amalgam

This creates build/quickjs-amalgam.zip containing:

quickjs-amalgam.c
quickjs.h
quickjs-libc.h

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

make distclean
# Or manually:
rm -rf build

Verifying the Build

After building, verify everything works:

Test the interpreter

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

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

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

Overview

Core Concepts

CLI Tools

Standard Library

Advanced Topics

Platform Support

Building from Source

Building from Source

Prerequisites

Standard Build

Build Types

Debug Build

Release Build

Shared Library Build

CMake Build Options

Example: Build with Options

Platform-Specific Builds

Windows

MinGW on Windows

Cross-Compilation

Amalgamated Build

Testing

Run Test262 Suite

Update Test Results

Advanced Build Options

Parallel Builds

Custom Installation Prefix

Static REPL Executable

Build with mimalloc

Cleaning Build Artifacts

Verifying the Build

Troubleshooting

Build Fails with Missing Dependencies

Linker Errors

Permission Errors During Install

Next Steps

Quick Start

API Reference

Examples

Contributing

​Building from Source

​Prerequisites

​Standard Build

​Build Types

​Debug Build

​Release Build

​Shared Library Build

​CMake Build Options

​Example: Build with Options

​Platform-Specific Builds

​Windows

​MinGW on Windows

​Cross-Compilation

​Amalgamated Build

​Testing

​Run Test262 Suite

​Update Test Results

​Advanced Build Options

​Parallel Builds

​Custom Installation Prefix

​Static REPL Executable

​Build with mimalloc

​Cleaning Build Artifacts

​Verifying the Build

​Troubleshooting

​Build Fails with Missing Dependencies

​Linker Errors

​Permission Errors During Install

​Next Steps

Quick Start

API Reference

Examples

Contributing

Building from Source

Prerequisites

Standard Build

Build Types

Debug Build

Release Build

Shared Library Build

CMake Build Options

Example: Build with Options

Platform-Specific Builds

Windows

MinGW on Windows

Cross-Compilation

Amalgamated Build

Testing

Run Test262 Suite

Update Test Results

Advanced Build Options

Parallel Builds

Custom Installation Prefix

Static REPL Executable

Build with mimalloc

Cleaning Build Artifacts

Verifying the Build

Troubleshooting

Build Fails with Missing Dependencies

Linker Errors

Permission Errors During Install

Next Steps