Skip to content

Building YAFU

Jump to bottom
bbuhrow edited this page Jun 19, 2026 · 4 revisions

Building YAFU

Pre-compiled Windows binaries are attached to each release for the most common ISA targets. For the best performance, build from source with the ISA flags appropriate to your CPU. The instruction set architecture (ISA) matters most for SIQS. ECM and the GGNFS lattice sievers are also accelerated on systems with AVX512.

Building the project is supported and has been tested on linux, wsl2, and windows via msys2/ucrt64. Windows builds are also supported using Microsoft Visual Studio.

The build on linux, wsl2, and msys2 is driven by a single unified Makefile, configured per-machine through config.mk. This same Makefile is used by YAFU's CI pipeline (Linux gcc + Windows MSYS2/MinGW-w64 gcc), so anything CI can produce, you can produce locally with the same command.

The MSVC build under build.vc22/ is configured through three MSBuild property sheets (Directory.Build.props, build_config.props, libs_and_extensions.props) and is currently a work in progress on the CI side; the IDE build works today.

For an overview of the CI matrix and the released artifacts, see Continuous Integration.

Dependencies

Required Optional
GMP — https://gmplib.org/ GMP-ECM — http://ecm.gforge.inria.fr/ (ECM factorization)
CUDA Toolkit (BATCH_CUDA, CUDA_POLY, CUDA_LA)
OpenCL (alternative to CUDA for GPU cofactorization)
MPI (parallel linear algebra)
zlib (savefile compression — disable with NO_ZLIB=1)

As of YAFU 3.0, ytools, ysieve, and msieve are bundled in the repo and built as part of the YAFU build.

Linux, WSL, and MSYS2/MinGW-w64

Quick start on linux or wsl2

cp config.mk.example config.mk       # first time only — edit if your deps aren't in standard locations
make USE_NATIVE=1 yafu               # builds with sensible defaults (gcc, release)

Quick start on msys2

cp config.mk.example config.mk       # first time only — edit if your deps aren't in standard locations and for ISA flags
make yafu                            # builds with sensible defaults (gcc, release)

That's it for a basic build. To pass options, either uncomment them in config.mk so they apply to every build, or pass them on the command line so they apply just to this one.

Top-level targets

Target Builds
yafu The main YAFU executable (default)
msieve The msieve static library + demo
siqs The siqs_demo standalone binary
ecm The ecm_demo standalone binary
all All four above
lasieve build the GGNFS lattice sievers (windows or linux)
info Print the fully resolved configuration — invaluable for debugging your setup
help Show the feature-flag reference baked into the Makefile
clean Remove build artifacts

make info will tell you what paths the Makefile found for GMP, GMP-ECM, CUDA, etc. — always run this first when something doesn't compile.

config.mk — local configuration

Copy config.mk.example to config.mk and edit the parts that apply to you. config.mk is gitignored on purpose, so each contributor's local paths and feature toggles never end up in commits.

The example file is grouped into four sections:

1. Dependency paths

# GMP_PREFIX        := ../gmp-install/6.2.1
# GMP_INCDIR        := $(GMP_PREFIX)/include
# GMP_LIBDIR        := $(GMP_PREFIX)/lib

# ECM_PREFIX        := ../ecm-install/7.0.6-wsl
# CUDA_PREFIX       := /usr/local/cuda-12
# OCL_PREFIX        := /opt/opencl

Set <DEP>_PREFIX for a self-contained install (<prefix>/include + <prefix>/lib), or set <DEP>_INCDIR and <DEP>_LIBDIR individually for split installations. Anything you don't set is auto-discovered by the Makefile from system paths (and CUDA_PATH / CUDA_ROOT for CUDA).

2. Feature flags

Move command-line options into the config so you don't retype them:

# OMP            := 1     # OpenMP threading
# ECM            := 1     # Link GMP-ECM and define HAVE_GMP_ECM
# BATCH_CUDA     := 1     # GPU cofactorization (CUDA or OpenCL)
# CUDA_POLY      := 1     # GPU NFS polynomial selection (CUDA)
# CUDA_LA        := 1     # GPU NFS linear algebra (CUDA)
# MPI            := 1     # MPI parallel processing (msieve LA)
# NO_ZLIB        := 1     # Disable zlib
# VBITS          := 128   # LA vector width: 64 (default), 128, 256
# STATIC_WIN     := 1     # Fully static Windows binary (MinGW/MSYS2)
# TOOLKIT_VERSION := 13   # CUDA toolkit major version (default 12)

Watch out: in config.mk, don't put inline comments after a value. The Makefile compares some variables to literal 1, and a trailing space or comment breaks the comparison. Put the comment on the line above.

3. ISA flags

Note: auto-discovered by USE_NATIVE=1 on linux.

To see your AVX flags on linux, wsl2, or msys2, use: lscpu | grep -oE 'avx[^\ ]+'

# USE_SSE41      := 1
# USE_AVX2       := 1
# USE_BMI2       := 1
# USE_AVX512     := 1
# USE_AVX512IFMA := 1
# USE_AVX512PF   := 1

Uncomment the highest level your CPU supports — see ISA flags and the implication chain below for details.

4. User overrides

# USER_CFLAGS  :=
# USER_LDFLAGS :=

Appended after all auto-generated flags, in case you need to add something the Makefile doesn't.

Compiler selection

make yafu CC=gcc          # default
make yafu CC=clang
make yafu CC=icc          # or CC=icx for the modern Intel compiler

Compiler family is auto-detected from the CC basename. ICC adds -qopt-report=5; clang adds clang-specific warning suppressions and, in debug builds, AddressSanitizer + UndefinedBehaviorSanitizer.

MPI=1 overrides CC with mpicc.

Debug vs release

make yafu DEBUG=1

Switches -O2 -DNDEBUG -fomit-frame-pointer → -O0 -g -DDEBUG. Under clang, debug builds also enable -fsanitize=address,undefined.

ISA flags and the implication chain

Enable only the highest level your CPU supports — everything below it is enabled automatically:

USE_AVX512IFMA → USE_AVX512 → USE_AVX2 → USE_SSE41
USE_AVX512PF   → USE_AVX512 → USE_BMI2
Flag Adds Targets
USE_SSE41=1 SSE 4.1 Core 2 / Penryn (2008) and newer
USE_AVX2=1 AVX2 (implies SSE 4.1) Haswell (2013) and newer — sweet spot for most modern CPUs
USE_BMI2=1 BMI / BMI2 Haswell and newer
USE_AVX512=1 AVX-512 F + BW (implies AVX2, BMI2) Skylake-X, Cascade Lake, Ice Lake, Tiger Lake, Zen 4, etc.
USE_AVX512IFMA=1 AVX-512 IFMA (implies USE_AVX512) Ice Lake and later — best ECM performance
USE_AVX512PF=1 AVX-512 PF (implies USE_AVX512) Xeon Phi / Knights Landing only

Other vector-related flags:

Flag Effect
VBITS=64|128|256|512 Linear-algebra vector width (default 64)
SMALLINT=1 Small SIQS intervals (Xeon Phi / KNL)
FORCE_GENERIC=1 Disable all SIMD paths — useful for building a "lowest common denominator" binary

Deprecated ISA aliases

These older names still work but print a deprecation notice at build time:

Deprecated Replacement
SKYLAKEX=1 USE_AVX512=1
ICELAKE=1 USE_AVX512IFMA=1
KNL=1 USE_AVX512PF=1 (and SMALLINT=1 if needed)

Optional feature flags (full list)

Flag Effect
OMP=1 OpenMP threading (-fopenmp -DHAVE_OMP)
ECM=1 Link GMP-ECM, enable ECM factorization (-DHAVE_GMP_ECM)
BATCH_CUDA=1 GPU cofactorization for NFS/SIQS (CUDA or OpenCL — Makefile auto-picks)
CUDA_POLY=1 GPU NFS polynomial selection (CUDA)
CUDA_LA=1 GPU NFS linear algebra (CUDA)
MPI=1 MPI parallel processing
BOINC=1 Link BOINC API (set BOINC_INC_DIR and BOINC_LIB_DIR)
CUDAAWARE=1 CUDA-aware MPI
NO_ZLIB=1 Disable zlib
PROFILE=1 gprof profiling (-pg; binary suffixed _prof)
OPT_DEBUG=1 Optimization debug output
TIMING=1 QS timing instrumentation
STATIC=1 Static link (experimental, Linux)
STATIC_WIN=1 Fully-static Windows .exe (MinGW/MSYS2 only)
MINGW=1 Building under MinGW (skip -ldl)
SM=NN CUDA compute capability (e.g. SM=80 for Ampere, SM=89 for Ada) — auto-detected from nvidia-smi when CUDA is present

Building the dependencies first

If GMP and GMP-ECM aren't already installed system-wide, here's a typical sequence. Exact make arguments may vary by system.

GMP

./configure --prefix="/path/to/a/gmp/install/location/"
make
make install

GMP-ECM

autoreconf -i
./configure --prefix="/path/to/a/ecm/install/location/" \
            --with-gmp="/path/to/a/gmp/install/location/"
make
make install

Then point YAFU at them through config.mk:

GMP_PREFIX := /path/to/a/gmp/install/location
ECM_PREFIX := /path/to/a/ecm/install/location

MSYS2 / MinGW-w64 (fully static Windows binaries)

The Windows releases shipped on the releases page are built with MSYS2/MinGW-w64 + STATIC_WIN=1. You can build the same way locally.

Install the toolchain and static deps via pacman:

pacman -S mingw-w64-x86_64-toolchain \
          mingw-w64-x86_64-gmp \
          mingw-w64-x86_64-zlib
# GMP-ECM: build from source as above, or pacman package if available

Then in the MSYS2 MinGW64 shell:

cp config.mk.example config.mk
# In config.mk, set:
#   STATIC_WIN := 1
#   ECM := 1
#   USE_AVX2 := 1     # or whichever ISA you want
make yafu

The result is a .exe that runs unmodified in cmd.exe or PowerShell — no DLLs needed alongside it.

BATCH_CUDA is not supported with STATIC_WIN=1 — OpenCL must be dynamically linked, and it's only available natively in MSYS2/MinGW-w64.

Windows — Visual Studio (MSVC)

Build files for MSVC live in build.vc22/. Visual Studio Community is free.

Property sheets

Configuration is centralized in three MSBuild property sheets at the top of build.vc22/:

File What it controls
Directory.Build.props Global settings inherited automatically by every project in the solution
build_config.props Toolset (e.g. v143, Intel oneAPI) and overall build configuration for x64 / Release
libs_and_extensions.props Paths to dependency builds, plus the PreprocessorDefinitions line where you enable ISA extensions for this build

Open each file in a text editor (or in Visual Studio's property sheet view) and adjust the values for your environment. Then build the yafu project in x64 / Release in Visual Studio.

Dependency layout

For the MSVC build you'll need separate builds of:

Dependency Source
mpir (or GMP) https://github.com/BrianGladman/mpir
ecm https://gitlab.inria.fr/zimmerma/ecm/-/releases or https://github.com/sethtroisi/gmp-ecm
pthreads https://github.com/BrianGladman/pthreads

All three ship working MSVC build files. Build them first, then point YAFU at them via the paths in libs_and_extensions.props (which are interpreted relative to YAFU's project directories — e.g. build.vc22\ecm).

The free Intel compiler also works inside Visual Studio 2022.

The CI pipeline currently relies on the Makefile legs (Linux gcc, MSYS2/MinGW gcc) for the released artifact matrix; the MSVC leg is being built out separately. If you only need to use YAFU on Windows, the MinGW-built releases are the canonical artifacts.

After building

No installation step — drop the binary wherever you like and run it. Files YAFU writes (logs, savefiles, yafu.ini) appear next to the binary, and lookup paths (e.g. for the GGNFS sievers) are resolved relative to it.

For NFS, point YAFU at GGNFS lattice sievers (ggnfs-lasieve4I*) via ggnfs_dir= in yafu.ini or -ggnfs_dir <path> on the command line. The repo ships builds under factor/lasieve5_64/bin/.

Legacy makefiles

The older toolchain-specific makefiles — Makefile.gcc, Makefile.clang, Makefile.icc — are still in the repo and may still build, but they don't get the new feature flags or auto-discovery and as of version 3.1.2, are no longer supported. New work should use Makefile and config.mk. If you have an existing setup driven by Makefile.gcc or similar, migrate when convenient.

Clone this wiki locally