Building from source — flashrom v1.7.0-devel (git:v1.6.0-35-gc54d0684) documentation

# Building from source

First thing, clone git repository for yourself (if you haven't done it already), see Set up the git repository and dev environment.

You're going to need the following tools to get started:

- gcc or clang

- meson

- ninja

- pkg-config

- sphinx-build*

* optional, to build man-pages and html documentation

And the following dependencies:

- cmocka [1]

- linux-headers [2]

- libpci [2]

- libusb1 [2]

- libftdi1 [2]

- libjaylink [2]

- NI-845x driver & library package [3]

- libcrypto [4]

[1]
optional, for building unit testing
[2] (1,2,3,4,5)
optional, depending on the selected programmer
[3]
optional, proprietary and Windows only. (See Windows build instructions)
[4]
optional, to enable RPMC commands

If you are cross compiling, install the dependencies for your target.

## TL;DR

    meson setup builddir
    meson compile -C builddir
    meson test -C builddir
    meson install -C builddir

## Installing dependencies

### Linux

- Debian / Ubuntu

      apt-get install -y \
      gcc meson ninja-build pkg-config python3-sphinx \
      libcmocka-dev libpci-dev libusb-1.0-0-dev libftdi1-dev libjaylink-dev \
      libssl-dev

- ArchLinux / Manjaro

      pacman -S --noconfirm \
      gcc meson ninja pkg-config python-sphinx cmocka \
      pciutils libusb libftdi libjaylink \
      openssl

- openSUSE / SUSE

      zypper install -y \
      gcc meson ninja pkg-config python3-Sphinx \
      libcmocka-devel pciutils-devel libusb-1_0-devel libftdi1-devel libjaylink-devel

- NixOS / nixpkgs

  - There is a `shell.nix` under `scripts/`

      nix-shell -p \
      gcc meson ninja pkg-config sphinx \
      cmocka pciutils libusb1 libftdi1 libjaylink

- Alpine Linux

      apk add \
      build-base meson ninja pkgconf py3-sphinx \
      cmocka-dev pciutils-dev libusb-dev libjaylink-dev

### Windows

- MSYS2

  Install MSYS2 and ensure it is fully updated.

  - `libpci` is not available through the package manager and pci based programmer are not supported on Windows.

  - `ni845x_spi` is only available with the proprietary library from National Instruments. Download and install the driver from ni.com and build flashrom for 32-bit. Add `-Dprogrammer=ni845x_spi` to your meson configuration.

  In the MINGW64 shell run:

      pacman -Sy \
      mingw-w64-x86_64-gcc mingw-w64-x86_64-meson mingw-w64-x86_64-ninja mingw-w64-x86_64-pkg-config mingw-w64-x86_64-python-sphinx \
      mingw-w64-x86_64-cmocka mingw-w64-x86_64-libusb mingw-w64-x86_64-libftdi mingw-w64-x86_64-libjaylink-git

  For building flashrom as 32-bit application, use the MSYS2 MINGW32 shell and run:

      pacman -Sy \
      mingw-w64-i686-gcc mingw-w64-i686-meson mingw-w64-i686-ninja mingw-w64-i686-pkg-config mingw-w64-i686-python-sphinx \
      mingw-w64-i686-cmocka mingw-w64-i686-libusb mingw-w64-i686-libftdi mingw-w64-i686-libjaylink-git

### MacOS

- Homebrew

  - `libpci` is not available through the package manager

  - `libjaylink` is not available through the package manager

      brew install \
      meson ninja pkg-config sphinx-doc \
      libusb libftdi

### BSD

- FreeBSD / DragonFlyBSD

  - `libusb1` is part of the system

  - `libjaylink` is not available through the package manager

      pkg install \
      meson ninja pkgconf py39-sphinx \
      cmocka libpci libftdi1

- OpenBSD

  - `libjaylink` is not available through the package manager

      pkg_add \
      meson ninja pkg-config py39-sphinx\
      cmocka pciutils libusb1 libftdi1

- NetBSD

  - `libjaylink` is not available through the package manager

  - note: https://www.cambus.net/installing-ca-certificates-on-netbsd/

      pkgin install \
      meson ninja pkg-config py39-sphinx \
      cmocka pciutils libusb1 libftdi1

### OpenIndiana (Illumos, Solaris, SunOS)

- `libpci` missing, pciutils is build without it

- `libftdi1` & `libjaylink` are not available through the package manager

- TODO: replace `build-essential` with the default compiler

    pkg install build-essential meson ninja cmocka libusb-1

### DJGPP-DOS

- Get DJGPP

- A great build script can be found here

- Download the pciutils sources

Run the following commands in the the pciutils directory to build libpci for DOS.
Replace `<DOS_INSTALL_ROOT>` with your cross-compile install root.

    make install-lib \
        ZLIB=no \
        DNS=no \
        HOST=i386-djgpp-djgpp \
        CROSS_COMPILE=i586-pc-msdosdjgpp- \
        STRIP="--strip-program=i586-pc-msdosdjgpp-strip -s" \
        PREFIX=<DOS_INSTALL_ROOT>

Point pkg-config to the `<DOS_INSTALL_ROOT>`

    export PKG_CONFIG_SYSROOT=<DOS_INSTALL_ROOT>

- To compile flashrom use the `meson_cross/i586_djgpp_dos.txt` cross-file

- You will need CWSDPMI.EXE to run flashrom

### libpayload

## Configuration

In the flashrom repository run:

    meson setup [builtin options] [flashrom options] <builddir>

Mesons `[builtin options]` can be displayed with `meson setup --help`. The flashrom specific options can be found in `meson_options.txt` in the top-level directory of flashrom and are used like in cmake with `-Doption=value` Run `meson configure` to display all configuration options.

## Configuration for Crossbuilds

Flashrom specific cross-files can be found in the `meson_cross` folder. To use them run:

    meson setup --cross-file <path/to/crossfile> [builtin options] [flashrom options] <builddir>

The options are the same as the normal configuration options. For more information see https://mesonbuild.com/Cross-compilation.html

## Compiling

Run:

    meson compile -C <builddir>

## Update configuration

If you want to change your initial configuration for some reason (for example you discovered that a programmer is missing), run:

    meson configure [updated builtin options] [updated flashrom options] <builddir>

## Unit Tests

To execute the unit tests run:

    meson test -C <builddir>

You will get a summary of the unit test results at the end.

### Code coverage

gcov

  Due to a bug in lcov, the html file will only be correct if lcov is not installed and gcovr is installed. See https://github.com/linux-test-project/lcov/issues/168 and https://github.com/mesonbuild/meson/issues/6747

  To create the coverage target add `-Db_coverage=true` to your build configuration. After executing the tests, you can run

      ninja -C <builddir> coverage

  to generate the coverage report.

lcov / llvm

  https://clang.llvm.org/docs/SourceBasedCodeCoverage.html Make sure that you are using clang as compiler, e.g. by setting CC=clang during configuration. Beside that you need to add `-Dllvm_cov=enabled` to your build configuration

      CC=clang meson setup -Dllvm_cov=enable <builddir>
      meson test -C <builddir>
      ninja -C <builddir> llvm-cov-tests

For additional information see the meson documentation

## Installing

To install flashrom and documentation, run:

    meson install -C <builddir>

This will install flashrom under the PREFIX selected in the configuration phase. Default is `/usr/local`.

To install into a different directory use DESTDIR, like this:

    DESTDIR=/your/destination/directory meson install -C <your_build_dir>

You can also set the prefix during configuration with:

    meson setup --prefix <DESTDIR> <your_build_dir>

## Create distribution package

To create a distribution tarball from your `builddir`, run:

    meson dist -C <builddir>

This will collect all git tracked files and pack them into an archive.

Current flashrom version is in the VERSION file. To release a new flashrom version you need to change VERSION file and tag the changing commit.