![[nodejs] pull LIEF dependency](https://releaserun.com/wp-content/uploads/2026/02/hero-1.jpg)
What You”ll Need
- Node.js source at v25.5.0 (clone from the Node.js Git repository)
- Git and developer tools: gcc/clang, make or MSVC, CMake, and Python 3 for build scripts
- Network access to download LIEF artifacts or source (or access to cached/proxied artifacts in CI)
- Optional: credentials for internal artifact registry if your environment blocks public downloads
How It Works
The Node.js v25.5.0 release added scripts and helper tooling inside the deps area to fetch LIEF as a third-party dependency. The tooling can either download prebuilt platform-specific LIEF binaries or clone and build LIEF from source, then place headers and libraries where Node”s build system can consume them.
At a high level the workflow is: locate the provided fetch/build script in the source tree, run it with platform and version options (or rely on defaults), set environment variables (for example LIEF_ROOT or LIEF_DIR) that point to the fetched artifacts, then reconfigure and rebuild Node so the linker and compiler pick up LIEF. The scripts are intended to simplify CI pipelines and local builds by encapsulating retrieval and install steps.
![[nodejs] pull LIEF dependency](https://nodejs.org/static/images/logo.svg){kind=logo}
Step-by-Step Guide
[nodejs] pull LIEF dependency
- Get the correct Node source: git clone –branch v25.5.0 https://github.com/nodejs/node.git && cd node
- Inspect the deps tooling: look under
deps/andtools/for LIEF fetch scripts (filenames often start with “lief” or “fetch-lief”). Read script –help or header comments to learn supported options like –version, –arch, –platform, and –prefix. - Fetch prebuilt LIEF (fast): run the provided fetch script with your platform and arch flags to download prebuilt artifacts. Example pattern:
./tools/deps/fetch-lief --platform linux --arch x64 --out deps/lief. If your script supports it, pass –version to pin a LIEF release. - Or build LIEF from source (if needed): if your environment requires a source build, use the script”s build mode or run CMake in the fetched LIEF source directory: configure with a preferred generator (Ninja/MSBuild), then build and install into a local prefix, e.g.,
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=deps/lief/install && cmake --build build --target install. - Point Node”s build to LIEF: set environment variables so Node”s configure can find LIEF, for example
export LIEF_ROOT=$(pwd)/deps/lief(or setLIEF_DIR/LIEF_PREFIXdepending on the provided scripts). Then run./configureand verify the output mentions LIEF include and lib paths. - Rebuild Node and verify: run
make -jor the platform appropriate build command. After build, run any tests that exercise binary parsing or native modules that link to LIEF, and verify symbols are resolved and runtime loads succeed.
Use Cases & Examples
- Local development for a native addon: you need LIEF headers and libs to compile an addon that inspects ELF/PE files. Use the fetch script to install LIEF into deps/lief, set
LIEF_ROOT, then compile your addon against those headers so CI and local dev match. - CI pipeline with cached artifacts: in CI, run the fetch step once and cache the installed
deps/liefdirectory between jobs. This avoids building LIEF repeatedly. The scripts added in v25.5.0 are meant to be deterministic so caches remain valid across runs. - Security tooling inside Node: if you add a diagnostic tool to Node that uses LIEF to parse binaries at runtime, pulling LIEF via the deps scripts ensures your production builds reference the same LIEF ABI that tests used during development.
Common Issues
- Network blocked: if downloads fail, mirror the LIEF artifacts to an internal registry and pass the script a –prefix or –mirror option, or download and place files under
deps/liefmanually. - ABI or version mismatch: Problem: Node build picks a different LIEF version than expected. Solution: pin the LIEF version with the script”s –version flag and clear any stale build caches before rebuilding.
- Missing headers at configure: Problem: configure can”t find
LIEFheaders. Solution: ensureLIEF_ROOT(or the script”s configured prefix) points to the install that containsinclude/andlib/, and rerun./configure. - Linker errors on Windows: Problem: unresolved externals. Solution: ensure you built LIEF with the same runtime and MSVC toolset as Node, and that .lib files are on the lib path referenced by the build.
What”s Next
- Integrate the LIEF fetch step into your CI cache strategy to speed builds
- Explore writing a Node native addon that uses LIEF APIs for binary inspection
- Track upstream LIEF releases and update the pinned LIEF version in your build scripts
Related Resources
- Node.js v25.5.0 release guide
- Official LIEF documentation: https://lief.quarkslab.com/
- Node.js BUILDING.md and developer docs for configuring third-party deps
Related Reading
- Node 20 vs 22 vs 24: Which LTS to Run — The Node.js version decision
- How to Add Version Health Badges — Track release health in your README
Troubleshooting Common LIEF Build Issues
Pulling the LIEF dependency into a local Node.js build is straightforward when everything aligns, but a few edge cases trip people up repeatedly. Here are the fixes.
CMake version mismatch. LIEF’s build scripts require CMake 3.24 or later. If your system ships an older version, the configure step fails silently and produces an incomplete libnode. Check with cmake --version before you start. On Ubuntu, the Kitware APT repository provides up-to-date packages.
Missing Python venv. Node.js’s build toolchain invokes Python for GYP and several code generators. Starting with v25.x, the project expects a virtual environment. Create one in the repo root with python3 -m venv .venv && source .venv/bin/activate before running ./configure.
Disk space on CI runners. A full debug build with LIEF symbols can exceed 12 GB. GitHub Actions runners provide roughly 14 GB of free space after the OS image. Use --without-inspector --without-intl flags to trim the build when you only need LIEF integration tests.
Cross-compilation caveats. If you target linux-arm64 from an x86 host, you must supply a LIEF toolchain file that matches the target triple. The Node.js embedding documentation covers the required environment variables for cross builds.
Complete build commands (copy-paste ready)
The article above walks through the concepts. Here are the exact commands in order, ready to run.
# Clone Node.js at v25.5.0
git clone --branch v25.5.0 --depth 1 https://github.com/nodejs/node.git
cd node
# Check the deps directory for LIEF-related scripts
find deps tools -name "*lief*" -o -name "*LIEF*" 2>/dev/null
ls deps/lief/ 2>/dev/null || echo "LIEF deps directory not yet populated"# Option A: Fetch prebuilt LIEF binaries (fastest)
# Detect platform and architecture
PLATFORM=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
echo "Building for: $PLATFORM $ARCH"
# Download LIEF release (check https://lief.re/download/ for latest)
LIEF_VERSION="0.16.0"
curl -LO "https://github.com/lief-project/LIEF/releases/download/${LIEF_VERSION}/LIEF-${LIEF_VERSION}-${PLATFORM}-${ARCH}.tar.gz"
mkdir -p deps/lief
tar xzf LIEF-${LIEF_VERSION}-${PLATFORM}-${ARCH}.tar.gz -C deps/lief --strip-components=1
# Verify the structure
ls deps/lief/include/LIEF/ # Should show header files
ls deps/lief/lib/ # Should show .a or .so files# Option B: Build LIEF from source (when you need custom config)
git clone --depth 1 https://github.com/lief-project/LIEF.git /tmp/lief-src
cd /tmp/lief-src
# Configure with CMake
cmake -S . -B build \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=$(pwd)/../node/deps/lief \
-DLIEF_PYTHON_API=OFF \
-DLIEF_EXAMPLES=OFF \
-DLIEF_TESTS=OFF
# Build and install
cmake --build build --parallel $(nproc)
cmake --install build
cd ../node # Back to Node source# Configure Node.js with LIEF
export LIEF_ROOT=$(pwd)/deps/lief
# Run Node's configure script
./configure --shared-lief \
--shared-lief-includes=${LIEF_ROOT}/include \
--shared-lief-libpath=${LIEF_ROOT}/lib
# Build Node.js
make -j$(nproc)
# Verify LIEF symbols are linked
nm out/Release/node | grep -i lief | head -5
# Should show LIEF-related symbols if linked correctly# CI caching strategy (GitHub Actions example)
# .github/workflows/build.yml
- name: Cache LIEF deps
uses: actions/cache@v4
with:
path: deps/lief
key: lief-${{ runner.os }}-${{ env.LIEF_VERSION }}
- name: Fetch LIEF (if not cached)
if: steps.cache.outputs.cache-hit != 'true'
run: |
curl -LO "https://github.com/lief-project/LIEF/releases/download/${LIEF_VERSION}/LIEF-${LIEF_VERSION}-Linux-x86_64.tar.gz"
mkdir -p deps/lief
tar xzf LIEF-*.tar.gz -C deps/lief --strip-components=1The official LIEF documentation covers the full API. For Node.js build system details, see BUILDING.md. Track Node.js releases and plan upgrades with the interactive release timeline or check your Node.js version health on the Node.js releases hub.
🛠️ Try These Free Tools
Paste your dependency file to check for end-of-life packages.
Plan your upgrade path with breaking change warnings and step-by-step guidance.
Paste your workflow YAML to audit action versions and pinning.
Track These Releases