Thomas Heijligen has uploaded this change for review. ( https://review.coreboot.org/c/flashrom/+/73359 )
Change subject: [WIP] doc: Add build instructions ......................................................................
[WIP] doc: Add build instructions
Those build instructions are mostly based on `Documentation/building.md` and the wiki. Some parts, e.g. the DOS and cross-compiling sections, are not fully working with the master branch yet. There are `.. todo::` sections which can be solved at a later stage.
Change-Id: I96771e98b313a6d26dd2be940ff37998d4124324 Signed-off-by: Thomas Heijligen thomas.heijligen@secunet.com --- D Documentation/building.md A doc/building_from_source.rst M doc/conf.py M doc/index.rst 4 files changed, 248 insertions(+), 148 deletions(-)
git pull ssh://review.coreboot.org:29418/flashrom refs/changes/59/73359/1
diff --git a/Documentation/building.md b/Documentation/building.md deleted file mode 100644 index e5d9412..0000000 --- a/Documentation/building.md +++ /dev/null @@ -1,147 +0,0 @@ -# Compiling from Source with meson (recommended) - -## Dependencies: - - * C compiler (GCC | Clang) * - * meson >=0.53.0 * - * ninja * - * pkg-config * - * cmocka ** - * system-headers *** - * libpci *** - * libusb1 >=1.0.9 *** - * libftdi1 *** - * libjaylink *** - -* Compile time dependency -** For unit-testing only -*** Runtime / Programmer specific - -## Build Options: - * classic_cli=auto/enabled/disabled - * classic_cli_default_programmer=<programmer_name>:<programmer_params> - * classic_cli_print_wiki=auto/enabled/disabled - * tests=auto/enabled/disabled - * ich_descriptors_tool=auto/enabled/disabled - * use_internal_dmi=true/false - * programmer=... - -## Configure -``` -meson builddir -D<your_options> -``` -- __builddir__ is the directory in which flashrom will be build -- for all available options see `meson_options.txt` - -## Compile -``` -ninja -C builddir -``` - -## Install -``` -ninja -C builddir install -``` - -## Run unit tests -``` -ninja -C builddir test -``` - -### Run unit tests with 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 -https://github.com/mesonbuild/meson/issues/6747 -``` -meson setup buildcov -Db_coverage=true -ninja -C buildcov test -ninja -C buildcov coverage -``` - -#### llvm -https://clang.llvm.org/docs/SourceBasedCodeCoverage.html -``` -env CC=clang meson setup buildclangcov -Dllvm_cov=enabled -ninja -C buildclangcov test -ninja -C buildclangcov llvm-cov-tests -``` - -## System specific information -### Ubuntu / Debian (Linux) - * __linux-headers__ are version specific -``` -apt-get install -y gcc meson ninja-build pkg-config libcmocka-dev \ - linux-headers-generic libpci-dev libusb-1.0-0-dev libftdi1-dev \ - libjaylink-dev -``` - -### ArchLinux / Manjaro - * __libjaylink__ is not available through the package manager -``` -pacman -S --noconfirm gcc meson ninja pkg-config cmocka \ - pciutils libusb libftdi -``` - -### NixOS / Nixpkgs -``` -nix-shell <flashrom_source>/util/shell.nix -``` -or -``` -nix-shell -p meson ninja pkg-config cmocka pciutils libusb1 libftdi1 libjaylink -``` - -### OpenSUSE -``` -zypper install -y gcc meson ninja pkg-config libcmocka-devel \ - pciutils-devel libusb-1_0-devel libftdi1-devel \ - libjaylink-devel -``` - -### Alpine -``` -apk add build-base meson ninja pkgconf cmocka-dev pciutils-dev libusb-dev libftdi1-dev libjaylink-dev linux-headers -``` - - -### Freebsd / DragonFly BSD - * Tests are not working yet and must be disabled with `-Dtests=disabled` - * __libjaylink__ is not available through the package manager - * __libusb1__ is part of the base system -``` -pkg install pkgconf meson ninja cmocka libpci libftdi1 -``` - -### OpenBSD - * Tests are not working yet and must be disabled with `-Dtests=disabled` - * __libjaylink__ is not available through the package manager -``` -pkg_add install meson ninja pkg-config cmocka pciutils libusb1 libftdi1 -``` - -### NetBSD - * Tests are not working yet and must be disabled with `-Dtests=disabled` - * __libjaylink__ is not available through the package manager - * note: https://www.cambus.net/installing-ca-certificates-on-netbsd/ -``` -pkgin install meson ninja pkg-config cmocka pciutils libusb1 libftdi1 -``` - -### OpenIndiana (Illumos, Solaris, SunOS) - * Tests are not working yet and must be disabled with `-Dtests=disabled` - * __libpci__ missing, pciutils is build without it - * __libftdi1__, __libjaylink__ is not available through the package manager - * TODO: replace __build-essential__ with the default compiler -``` -pkg install build-essential meson ninja cmocka libusb-1 -``` - -### MacOS (Homebrew) - * Tests are not working yet and must be disabled with `-Dtests=disabled` - * Internal, PCI programmer not supported - * __libjaylink__ is not available through the package manager -``` -brew install meson ninja pkg-config cmocka libusb libftdi -``` diff --git a/doc/building_from_source.rst b/doc/building_from_source.rst new file mode 100644 index 0000000..f850c3d --- /dev/null +++ b/doc/building_from_source.rst @@ -0,0 +1,226 @@ +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* +* linux-headers** +* libpci** +* libusb1** +* libftdi1** +* libjaylink** + +| * optional, for building unit testing +| ** optional, depending on the selected programmer + +If you are cross compiling, install the dependencies for your target. + +TL;DR +---- +:: + + meson setup build + meson compile -C build + meson install -C build + + +Installing dependencies +----------------------- + +.. todo:: Move the bullet points to `tabs https://www.w3schools.com/howto/howto_js_tabs.asp`_ + + * 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 + .. todo:: Add build instructions to build under MSYS2, CYGWIN or cross compiling from Linux + +* 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 py-sphinx \ + cmocka libpci libftdi + + * OpenBSD + * ``libjaylink`` is not available through the package manager + :: + + pkg_add install \ + meson ninja pkg-config py-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 py-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 https://www.delorie.com/djgpp/`_ + * A great build script can be found `here https://github.com/andrewwutw/build-djgpp`_ + * Download the `pciutils https://mj.ucw.cz/sw/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 https://sandmann.dotster.com/cwsdpmi/`_ to run flashrom + +* libpayload + .. todo:: Add building instructions for 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`` + +.. todo:: Write a sphinx extension to render ``meson_options.txt`` here + + +Configuration for Crossbuilds +----------------------------- +Flashrom specific ross-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> + + +Reconfiguration +--------------- +If you are not happy with the initial configuration, e.g. a programmer is missing, +or you want to review it, run:: + + meson configure [updated builtin options] [updated flashrom options] + + +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. + +To get a code coverage report install ``gcovr`` for GCC or ``lcov`` and ``gen-html`` for LLVM +and reconfigure the build with ``-Db_coverage=true``. Run:: + + ninja -C <builddir> coverage + +For more information see `the meson documentation https://mesonbuild.com/Unit-tests.html#coverage`_ + +Installing +---------- +Run:: + + meson install -C <builddir> + +This will install flashrom under the PREFIX selected in the configuration phase. Default is ``/usr/local``. + + +Create distribution package +--------------------------- +To create a distribution tarball from your <builddir>, run:: + + meson dist -C <builddir> diff --git a/doc/conf.py b/doc/conf.py index d06f538..42bda1f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -18,11 +18,15 @@
master_doc = 'index' # this is needed for old versions
-extensions = [] +extensions = [ + 'sphinx.ext.todo' +]
#templates_path = ['_templates'] exclude_patterns = []
+todo_include_todos = True +
# -- Options for HTML output ------------------------------------------------- diff --git a/doc/index.rst b/doc/index.rst index d309a03..c12a321 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,6 +6,7 @@ .. toctree:: :hidden:
+ building_from_source classic_cli_manpage
.. include:: ../README
-
Thomas Heijligen (Code Review)