Thomas Heijligen has uploaded this change for review.
[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
To view, visit change 73359. To unsubscribe, or for help writing mail filters, visit settings.