mirror of
https://review.coreboot.org/flashrom.git
synced 2025-07-03 15:03:22 +02:00
doc: Convert build documentation to sphinx
These build instructions are mostly based on `Documentation/building.md` and the wiki. There are some `.. todo::` sections still present in the documentation. They will be completed later. For some of the todos content needs to be written, some others require custom sphinx-plugins to be implemented. The `.. todo::` sections are only visible in the source, not in the rendered html. Change-Id: I96771e98b313a6d26dd2be940ff37998d4124324 Signed-off-by: Thomas Heijligen <thomas.heijligen@secunet.com> Reviewed-on: https://review.coreboot.org/c/flashrom/+/73359 Reviewed-by: Alexander Goncharov <chat@joursoir.net> Reviewed-by: Edward O'Callaghan <quasisec@chromium.org> Reviewed-by: Anastasia Klimchuk <aklm@chromium.org> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
This commit is contained in:
Thomas Heijligen
committed by
Anastasia Klimchuk
Anastasia Klimchuk
parent
70af6ea5c9
commit
806a3fd4d5
@ -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
|
|
||||||
```
|
|
||||||
10
doc/conf.py
10
doc/conf.py
@ -17,11 +17,19 @@ author = 'The flashrom authors'
|
|||||||
|
|
||||||
master_doc = 'index' # this is needed for old versions
|
master_doc = 'index' # this is needed for old versions
|
||||||
|
|
||||||
extensions = []
|
extensions = [
|
||||||
|
'sphinx.ext.todo'
|
||||||
|
]
|
||||||
|
|
||||||
#templates_path = ['_templates']
|
#templates_path = ['_templates']
|
||||||
exclude_patterns = []
|
exclude_patterns = []
|
||||||
|
|
||||||
|
# -- Options for Todo extension ----------------------------------------------
|
||||||
|
# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
|
||||||
|
|
||||||
|
# If this is True, todo and todolist produce output, else they produce nothing. The default is False.
|
||||||
|
todo_include_todos = False
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
# -- Options for HTML output -------------------------------------------------
|
# -- Options for HTML output -------------------------------------------------
|
||||||
|
|||||||
254
doc/dev_guide/building_from_source.rst
Normal file
254
doc/dev_guide/building_from_source.rst
Normal file
@ -0,0 +1,254 @@
|
|||||||
|
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 builddir
|
||||||
|
meson compile -C builddir
|
||||||
|
meson install -C builddir
|
||||||
|
|
||||||
|
|
||||||
|
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 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 <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``
|
||||||
|
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 <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 <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>
|
||||||
7
doc/dev_guide/index.rst
Normal file
7
doc/dev_guide/index.rst
Normal file
@ -0,0 +1,7 @@
|
|||||||
|
Developers documentation
|
||||||
|
========================
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
building_from_source
|
||||||
@ -6,6 +6,7 @@
|
|||||||
.. toctree::
|
.. toctree::
|
||||||
:hidden:
|
:hidden:
|
||||||
|
|
||||||
|
dev_guide/index
|
||||||
classic_cli_manpage
|
classic_cli_manpage
|
||||||
|
|
||||||
.. include:: ../README
|
.. include:: ../README
|
||||||
|
|||||||
Reference in New Issue
Block a user