1Building from source 2==================== 3 4You're going to need the following tools to get started: 5 6* gcc or clang 7* meson 8* ninja 9* pkg-config 10* sphinx-build* 11 12| \* optional, to build man-pages and html documentation 13 14And the following dependencies: 15 16* cmocka [#b1]_ 17* linux-headers [#b2]_ 18* libpci [#b2]_ 19* libusb1 [#b2]_ 20* libftdi1 [#b2]_ 21* libjaylink [#b2]_ 22* NI-845x driver & library package [#b3]_ 23 24.. [#b1] | optional, for building unit testing 25.. [#b2] | optional, depending on the selected programmer 26.. [#b3] | optional, proprietary and Windows only. (See Windows build instructions) 27 28If you are cross compiling, install the dependencies for your target. 29 30TL;DR 31----- 32:: 33 34 meson setup builddir 35 meson compile -C builddir 36 meson test -C builddir 37 meson install -C builddir 38 39 40.. _installing-dependencies: 41 42Installing dependencies 43----------------------- 44 45.. todo:: Move the bullet points to `tabs <https://www.w3schools.com/howto/howto_js_tabs.asp>`_ 46 47 * No external dependencies (documentation should be build without fetching all of pypi) 48 * No Javascript? 49 50Linux 51""""" 52 53* Debian / Ubuntu 54 55 :: 56 57 apt-get install -y \ 58 gcc meson ninja-build pkg-config python3-sphinx \ 59 libcmocka-dev libpci-dev libusb-1.0-0-dev libftdi1-dev libjaylink-dev 60 61* ArchLinux / Manjaro 62 63 :: 64 65 pacman -S --noconfirm \ 66 gcc meson ninja pkg-config python-sphinx cmocka \ 67 pciutils libusb libftdi libjaylink 68 69* openSUSE / SUSE 70 71 :: 72 73 zypper install -y \ 74 gcc meson ninja pkg-config python3-Sphinx \ 75 libcmocka-devel pciutils-devel libusb-1_0-devel libftdi1-devel libjaylink-devel 76 77* NixOS / nixpkgs 78 79 * There is a ``shell.nix`` under ``scripts/`` 80 81 :: 82 83 nix-shell -p \ 84 gcc meson ninja pkg-config sphinx \ 85 cmocka pciutils libusb1 libftdi1 libjaylink 86 87* Alpine Linux 88 89 :: 90 91 apk add \ 92 build-base meson ninja pkgconf py3-sphinx \ 93 cmocka-dev pciutils-dev libusb-dev libjaylink-dev 94 95Windows 96""""""" 97 98* MSYS2 99 100 Install `MSYS2 <https://www.msys2.org/>`_ and ensure it is `fully updated <https://www.msys2.org/docs/updating/>`_. 101 102 * ``libpci`` is not available through the package manager and pci based programmer are not supported on Windows. 103 * ``ni845x_spi`` is only available with the proprietary library from National Instruments. Download and install the driver 104 from `ni.com <https://www.ni.com/en-us/support/downloads/drivers/download.ni-845x-driver-software.html>`_ and build flashrom 105 for **32-bit**. Add ``-Dprogrammer=ni845x_spi`` to your meson configuration. 106 107 In the MINGW64 shell run:: 108 109 pacman -Sy \ 110 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 \ 111 mingw-w64-x86_64-cmocka mingw-w64-x86_64-libusb mingw-w64-x86_64-libftdi mingw-w64-x86_64-libjaylink-git 112 113 For building flashrom as 32-bit application, use the MSYS2 MINGW32 shell and run:: 114 115 pacman -Sy \ 116 mingw-w64-i686-gcc mingw-w64-i686-meson mingw-w64-i686-ninja mingw-w64-i686-pkg-config mingw-w64-i686-python-sphinx \ 117 mingw-w64-i686-cmocka mingw-w64-i686-libusb mingw-w64-i686-libftdi mingw-w64-i686-libjaylink-git 118 119MacOS 120""""" 121 122* Homebrew 123 124 * ``libpci`` is not available through the package manager 125 * ``libjaylink`` is not available through the package manager 126 127 :: 128 129 brew install \ 130 meson ninja pkg-config sphinx-doc \ 131 libusb libftdi 132 133BSD 134""" 135 136* FreeBSD / DragonFlyBSD 137 138 * ``libusb1`` is part of the system 139 * ``libjaylink`` is not available through the package manager 140 141 :: 142 143 pkg install \ 144 meson ninja pkgconf py39-sphinx \ 145 cmocka libpci libftdi1 146 147* OpenBSD 148 149 * ``libjaylink`` is not available through the package manager 150 151 :: 152 153 pkg_add \ 154 meson ninja pkg-config py39-sphinx\ 155 cmocka pciutils libusb1 libftdi1 156 157* NetBSD 158 159 * ``libjaylink`` is not available through the package manager 160 * note: https://www.cambus.net/installing-ca-certificates-on-netbsd/ 161 162 :: 163 164 pkgin install \ 165 meson ninja pkg-config py39-sphinx \ 166 cmocka pciutils libusb1 libftdi1 167 168OpenIndiana (Illumos, Solaris, SunOS) 169""""""""""""""""""""""""""""""""""""" 170 171* ``libpci`` missing, pciutils is build without it 172* ``libftdi1`` & ``libjaylink`` are not available through the package manager 173* TODO: replace ``build-essential`` with the default compiler 174 175:: 176 177 pkg install build-essential meson ninja cmocka libusb-1 178 179DJGPP-DOS 180""""""""" 181 182* Get `DJGPP <https://www.delorie.com/djgpp/>`_ 183* A great build script can be found `here <https://github.com/andrewwutw/build-djgpp>`_ 184* Download the `pciutils <https://mj.ucw.cz/sw/pciutils/>`_ sources 185 186| Run the following commands in the the pciutils directory to build libpci for DOS. 187| Replace ``<DOS_INSTALL_ROOT>`` with your cross-compile install root. 188 189:: 190 191 make install-lib \ 192 ZLIB=no \ 193 DNS=no \ 194 HOST=i386-djgpp-djgpp \ 195 CROSS_COMPILE=i586-pc-msdosdjgpp- \ 196 STRIP="--strip-program=i586-pc-msdosdjgpp-strip -s" \ 197 PREFIX=<DOS_INSTALL_ROOT> 198 199Point pkg-config to the ``<DOS_INSTALL_ROOT>`` :: 200 201 export PKG_CONFIG_SYSROOT=<DOS_INSTALL_ROOT> 202 203* To compile flashrom use the ``meson_cross/i586_djgpp_dos.txt`` cross-file 204* You will need `CWSDPMI.EXE <https://sandmann.dotster.com/cwsdpmi/>`_ to run flashrom 205 206libpayload 207"""""""""" 208 209 .. todo:: Add building instructions for libpayload 210 211 212Configuration 213------------- 214In the flashrom repository run:: 215 216 meson setup [builtin options] [flashrom options] <builddir> 217 218Mesons ``[builtin options]`` can be displayed with ``meson setup --help``. 219The flashrom specific options can be found in ``meson_options.txt`` in the top-level 220directory of flashrom and are used like in cmake with ``-Doption=value`` 221Run ``meson configure`` to display all configuration options. 222 223.. todo:: Write a sphinx extension to render ``meson_options.txt`` here 224 225 226Configuration for Crossbuilds 227----------------------------- 228Flashrom specific cross-files can be found in the ``meson_cross`` folder. 229To use them run:: 230 231 meson setup --cross-file <path/to/crossfile> [builtin options] [flashrom options] <builddir> 232 233The options are the same as the normal configuration options. For more information see 234https://mesonbuild.com/Cross-compilation.html 235 236 237Compiling 238--------- 239Run:: 240 241 meson compile -C <builddir> 242 243 244Update configuration 245-------------------- 246If you want to change your initial configuration for some reason 247(for example you discovered that a programmer is missing), run:: 248 249 meson configure [updated builtin options] [updated flashrom options] <builddir> 250 251.. _unit tests: 252 253Unit Tests 254---------- 255To execute the unit tests run:: 256 257 meson test -C <builddir> 258 259You will get a summary of the unit test results at the end. 260 261 262Code coverage 263""""""""""""" 264gcov 265 Due to a bug in lcov, the html file will only be correct if lcov is not 266 installed and gcovr is installed. See 267 https://github.com/linux-test-project/lcov/issues/168 and 268 https://github.com/mesonbuild/meson/issues/6747 269 270 To create the coverage target add ``-Db_coverage=true`` to your build configuration. 271 After executing the tests, you can run :: 272 273 ninja -C <builddir> coverage 274 275 to generate the coverage report. 276 277lcov / llvm 278 https://clang.llvm.org/docs/SourceBasedCodeCoverage.html 279 Make sure that you are using `clang` as compiler, e.g. by setting `CC=clang` during configuration. 280 Beside that you need to add ``-Dllvm_cov=enabled`` to your build configuration :: 281 282 CC=clang meson setup -Dllvm_cov=enable <builddir> 283 meson test -C <builddir> 284 ninja -C <builddir> llvm-cov-tests 285 286For additional information see `the meson documentation <https://mesonbuild.com/Unit-tests.html#coverage>`_ 287 288 289Installing 290---------- 291To install flashrom and documentation, run:: 292 293 meson install -C <builddir> 294 295This will install flashrom under the PREFIX selected in the configuration phase. Default is ``/usr/local``. 296 297To install into a different directory use DESTDIR, like this:: 298 299 DESTDIR=/your/destination/directory meson install -C <your_build_dir> 300 301You can also set the prefix during configuration with:: 302 303 meson setup --prefix <DESTDIR> <your_build_dir> 304 305Create distribution package 306--------------------------- 307To create a distribution tarball from your ``builddir``, run:: 308 309 meson dist -C <builddir> 310 311This will collect all git tracked files and pack them into an archive. 312 313Current flashrom version is in the VERSION file. To release a new flashrom 314version you need to change VERSION file and tag the changing commit. 315