Building from source ==================== 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 [#b1]_ * linux-headers [#b2]_ * libpci [#b2]_ * libusb1 [#b2]_ * libftdi1 [#b2]_ * libjaylink [#b2]_ * NI-845x driver & library package [#b3]_ .. [#b1] | optional, for building unit testing .. [#b2] | optional, depending on the selected programmer .. [#b3] | optional, proprietary and Windows only. (See Windows build instructions) 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: Installing dependencies ----------------------- .. todo:: Move the bullet points to `tabs `_ * No external dependencies (documentation should be build without fetching all of pypi) * No Javascript? 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 * ArchLinux / Manjaro :: pacman -S --noconfirm \ gcc meson ninja pkg-config python-sphinx cmocka \ pciutils libusb libftdi libjaylink * 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 ```` 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= Point pkg-config to the ```` :: export PKG_CONFIG_SYSROOT= * To compile flashrom use the ``meson_cross/i586_djgpp_dos.txt`` cross-file * You will need `CWSDPMI.EXE `_ to run flashrom libpayload """""""""" .. todo:: Add building instructions for libpayload Configuration ------------- In the flashrom repository run:: meson setup [builtin options] [flashrom options] 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. .. todo:: Write a sphinx extension to render ``meson_options.txt`` here Configuration for Crossbuilds ----------------------------- Flashrom specific cross-files can be found in the ``meson_cross`` folder. To use them run:: meson setup --cross-file [builtin options] [flashrom options] 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 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] .. _unit tests: Unit Tests ---------- To execute the unit tests run:: meson test -C 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 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 meson test -C ninja -C llvm-cov-tests For additional information see `the meson documentation `_ Installing ---------- To install flashrom and documentation, run:: meson install -C 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 You can also set the prefix during configuration with:: meson setup --prefix Create distribution package --------------------------- To create a distribution tarball from your ``builddir``, run:: meson dist -C 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.