Attention is currently required from: Thomas Heijligen, Stefan Reinauer, Alexander Goncharov.
Hello build bot (Jenkins), Stefan Reinauer, Thomas Heijligen, Alexander Goncharov,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/flashrom/+/74216
to look at the new patch set (#3).
Change subject: doc: Convert README to sphinx
......................................................................
doc: Convert README to sphinx
This patch also includes small changes to README file that were
agreed earlier:
changing all links to https
re-ordering of sections as Build instructions, Installations,
Packaging, Contact
Change-Id: I6e0debc0e15a9c4866f6d16fb010cd3f13171ff3
Signed-off-by: Anastasia Klimchuk <aklm(a)chromium.org>
---
R README.rst
M doc/index.rst
2 files changed, 120 insertions(+), 69 deletions(-)
git pull ssh://review.coreboot.org:29418/flashrom refs/changes/16/74216/3
--
To view, visit https://review.coreboot.org/c/flashrom/+/74216
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: flashrom
Gerrit-Branch: master
Gerrit-Change-Id: I6e0debc0e15a9c4866f6d16fb010cd3f13171ff3
Gerrit-Change-Number: 74216
Gerrit-PatchSet: 3
Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Alexander Goncharov <chat(a)joursoir.net>
Gerrit-Reviewer: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-Attention: Thomas Heijligen <src(a)posteo.de>
Gerrit-Attention: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Gerrit-Attention: Alexander Goncharov <chat(a)joursoir.net>
Gerrit-MessageType: newpatchset
Attention is currently required from: Edward O'Callaghan, Alexander Goncharov.
Anastasia Klimchuk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/66535 )
Change subject: cli_classic: move version output outside of parsing
......................................................................
Patch Set 2:
(1 comment)
File cli_classic.c:
https://review.coreboot.org/c/flashrom/+/66535/comment/2a25fb2a_77839c3d
PS2, Line 817: /* print_version() is always called during startup. */
Is this comment saying the version option is not needed, because version is always printed no matter what?
I am wondering... is there a way to optimise the situation
--
To view, visit https://review.coreboot.org/c/flashrom/+/66535
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: flashrom
Gerrit-Branch: master
Gerrit-Change-Id: I1e6849a734480deed030191fa5e7066b1da4f23a
Gerrit-Change-Number: 66535
Gerrit-PatchSet: 2
Gerrit-Owner: Alexander Goncharov <chat(a)joursoir.net>
Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Edward O'Callaghan <quasisec(a)chromium.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-Attention: Edward O'Callaghan <quasisec(a)chromium.org>
Gerrit-Attention: Alexander Goncharov <chat(a)joursoir.net>
Gerrit-Comment-Date: Thu, 27 Apr 2023 10:53:24 +0000
Gerrit-HasComments: Yes
Gerrit-Has-Labels: No
Gerrit-MessageType: comment
Attention is currently required from: Edward O'Callaghan, Alexander Goncharov.
Anastasia Klimchuk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/66532 )
Change subject: cli_classic: move validation of incompatible options to one place
......................................................................
Patch Set 6:
(2 comments)
Patchset:
PS6:
Another note on testing: all the invalid combinations can be tested with dummy. Even the options which are not supported by dummy, because cli is expected to abort+message early and not call the programmer code.
File cli_classic.c:
https://review.coreboot.org/c/flashrom/+/66532/comment/37ca370b_0bfe61a7
PS2, Line 560: validate_options(
> I think if the branches are all in here now then you will need to ensure this function is called con […]
I was thinking about it, this patch moves validation into `parse_options` which has to be called, because the options has to be parsed. Do you mean to ensure `validate_options` is called inside `parse_options`?
--
To view, visit https://review.coreboot.org/c/flashrom/+/66532
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: flashrom
Gerrit-Branch: master
Gerrit-Change-Id: If6d7579847cc8ae13b54ef7bd50072a9402f835f
Gerrit-Change-Number: 66532
Gerrit-PatchSet: 6
Gerrit-Owner: Alexander Goncharov <chat(a)joursoir.net>
Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Edward O'Callaghan <quasisec(a)chromium.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-Attention: Edward O'Callaghan <quasisec(a)chromium.org>
Gerrit-Attention: Alexander Goncharov <chat(a)joursoir.net>
Gerrit-Comment-Date: Thu, 27 Apr 2023 10:02:59 +0000
Gerrit-HasComments: Yes
Gerrit-Has-Labels: No
Comment-In-Reply-To: Edward O'Callaghan <quasisec(a)chromium.org>
Gerrit-MessageType: comment
Attention is currently required from: Edward O'Callaghan, Alexander Goncharov.
Anastasia Klimchuk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/66531 )
Change subject: cli_classic: wrap options validation in function
......................................................................
Patch Set 5: Code-Review+1
(1 comment)
Patchset:
PS5:
If you could rebase and test with dummy, that would be great, thanks!
--
To view, visit https://review.coreboot.org/c/flashrom/+/66531
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: flashrom
Gerrit-Branch: master
Gerrit-Change-Id: Ib5685eb5ee3810ef2efd40a3901340e2ceb229ff
Gerrit-Change-Number: 66531
Gerrit-PatchSet: 5
Gerrit-Owner: Alexander Goncharov <chat(a)joursoir.net>
Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Edward O'Callaghan <quasisec(a)chromium.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-CC: Thomas Heijligen <src(a)posteo.de>
Gerrit-Attention: Edward O'Callaghan <quasisec(a)chromium.org>
Gerrit-Attention: Alexander Goncharov <chat(a)joursoir.net>
Gerrit-Comment-Date: Thu, 27 Apr 2023 09:48:49 +0000
Gerrit-HasComments: Yes
Gerrit-Has-Labels: Yes
Gerrit-MessageType: comment
Anastasia Klimchuk has submitted this change. ( https://review.coreboot.org/c/flashrom/+/73822 )
(
6 is the latest approved patch-set.
No files were changed between the latest approved patch-set and the submitted one.
)Change subject: doc: Add contact page
......................................................................
doc: Add contact page
This is just a copy of https://www.flashrom.org/Contact.
Change-Id: Ibfba6a59c5a945b4238d16e07a07584f94159568
Signed-off-by: Thomas Heijligen <thomas.heijligen(a)secunet.com>
Reviewed-on: https://review.coreboot.org/c/flashrom/+/73822
Reviewed-by: Anastasia Klimchuk <aklm(a)chromium.org>
Reviewed-by: Edward O'Callaghan <quasisec(a)chromium.org>
Tested-by: build bot (Jenkins) <no-reply(a)coreboot.org>
---
A doc/contact.rst
M doc/index.rst
2 files changed, 160 insertions(+), 0 deletions(-)
Approvals:
build bot (Jenkins): Verified
Edward O'Callaghan: Looks good to me, approved
Anastasia Klimchuk: Looks good to me, approved
diff --git a/doc/contact.rst b/doc/contact.rst
new file mode 100644
index 0000000..3a29c24
--- /dev/null
+++ b/doc/contact.rst
@@ -0,0 +1,143 @@
+Contact
+========
+.. The extra = is needed to prevent git from throwing a `leftover conflict marker`
+ error when commiting.
+
+Mailing List
+------------
+Flashrom related mails are welcome on the flashrom mailing list at `flashrom(a)flashrom.org <mailto:flashrom@flashrom.org>`_.
+Please do NOT send any BIOS images or F segment dumps to the list!
+
+E-mails with binary files attached will be rejected. Images for things such as scope or logic analyzer traces are acceptable
+if hosted on a third-party photo sharing service that assigns a unique URL to the image, such as Google Photos.
+This prevents the photo URL from being abused for malicious or inappropriate content.
+
+Please note that the list is moderated for non-subscribers and we recommend to subscribe first.
+
+Subscription
+""""""""""""
+https://mail.coreboot.org/postorius/lists/flashrom.flashrom.org/
+
+Archives
+""""""""
+| https://mail.coreboot.org/hyperkitty/list/flashrom@flashrom.org/
+| https://www.flashrom.org/pipermail/flashrom/ (Up to Dec. 2018)
+| https://marc.info/?l=flashrom
+| https://www.mail-archive.com/flashrom@flashrom.org/
+
+Moderation rules
+""""""""""""""""
+If your mail is too big (the current limit is 256 kB) or if you're not on the subscriber list, your mail will be held for moderation.
+If your mail contains any BIOS images or F segment dumps (instead of links which are fine), the mail will be rejected for legal reasons
+(we do not have the right to distribute BIOS images).
+
+IRC
+---
+Some of the flashrom developers and users hang out in the `#flashrom <irc://irc.libera.chat/#flashrom>`_
+channel on the `Libera.chat <https://www.libera.chat/>`_ `IRC <https://en.wikipedia.org/wiki/Internet_Relay_Chat>`_ network.
+If you don't have an IRC client, you can use the Libera.chat `webchat <https://web.libera.chat/#flashrom>`_.
+
+**#flashrom** channel is bridged to `Matrix <https://matrix.org/>`_.
+If you would like to join, you can use `this invite link <https://matrix.to/#/#flashrom:libera.chat>`_.
+
+Here you have the chance to talk to people being involved or interested in this project.
+Most of the discussion is tech talk and user help.
+
+Do note that IRC's nature has a significant effect on conversations. People from all over the world can join this channel
+with many different cultures and timezones. Most people are in the `CET timezone <https://en.wikipedia.org/wiki/Central_European_Time>`_,
+so the channel may be very quiet during `CET nighttime <https://time.is/CET>`_.
+
+If you have a problem and would like to get help, don't ask for help. Instead, just **explain** your problem right away,
+and make sure to **describe** the situation as much as possible, so that other people can understand you and provide meaningful answers.
+Otherwise, others have to ask or guess the details of your problem, which is frustrating for both parties.
+
+If you receive no replies, **please be patient**.
+After all, silence is better than getting replied with `"IDK" <https://en.wiktionary.org/wiki/IDK>`_.
+Frequently, somebody knows the answer, but hasn't checked IRC yet. In any case, please **do not leave the channel while waiting for an answer!**
+Since IRC does not store messages, replying to somebody who left the channel is **impossible**.
+
+To have persistence on IRC, you can set up an `IRC bouncer <https://en.wikipedia.org/wiki/Internet_Relay_Chat#Bouncer>`_
+like `ZNC <https://en.wikipedia.org/wiki/ZNC>`_, or use `IRCCloud <https://www.irccloud.com/>`_.
+Please **do not publish any logs** of this channel.
+
+Most of the time, people use IRC on wider-than-tall screens. Because of this, consider that pressing the return key is expensive.
+Instead of sending lots of tiny messages with only about two words, prefer using longer sentences, spaces and punctuation symbols.
+If reading and understanding your messages is easy, replying to them is also easy.
+
+Should you need to paste lots of text (more than three lines), please use a `paste service <https://en.wikipedia.org/wiki/Pastebin>`_.
+For flashrom logs, feel free to use `paste.flashrom.org <https://paste.flashrom.org>`_.
+Other good paste services are `ix.io <http://ix.io/>`_, `paste.rs <https://paste.rs/>`_, `bpaste.net <https://bpaste.net/>`_,
+`gist.github.com <https://gist.github.com/>`_ and `dpaste.com <http://dpaste.com/>`_.
+
+Questions on `coreboot <https://coreboot.org>`_, `OpenBIOS <http://www.openbios.info/>`_, firmware and related topics are welcome in **#coreboot** on the same server.
+
+Dev meeting
+-----------
+Flashrom developers community runs an online meeting every two weeks.
+The main purpose of the meeting is to discuss development plans, ideas,
+current ongoing projects, pending patches, and sometimes organisational questions.
+
+Note this meeting is NOT:
+
+* troubleshooting session
+* tech support forum
+* user training session
+
+For questions above, please use IRC or the mailing list.
+
+Time of meeting
+"""""""""""""""
+It runs once every two weeks.
+
+**IMPORTANT**: please calculate meeting time for your local timezone.
+
+Between November and March (inclusive)
+
+ **Wednesday 21:00-22:00 UTC+0**
+
+ also known as
+
+ | Wednesday 13.00-14.00 Pacific Standard Time UTC-8
+ | Wednesday 22.00-23.00 Central European Time UTC+1
+ | Thursday 8.00-9.00am Australian Eastern Daylight Time UTC+11
+
+Between April and September (inclusive)
+
+ **Thursday 6.00-7.00am UTC+0**
+
+ also known as
+
+ | Wednesday 11pm-midnight Pacific Daylight Time UTC-7
+ | Thursday 8.00-9.00am Central European Summer Time UTC+2
+ | Thursday 16.00-17.00 Australian Eastern Standard Time UTC+10
+
+The last week of March and 4 weeks of October there are no meetings
+This is because daylight saving time changes are happening on different dates in different locations, and setting up meeting time becomes too complicated.
+
+FAQ
+---
+**When is the next meeting?**
+
+Look into the meeting notes `document <https://docs.google.com/document/d/18qKvEbfPszjsJJGJhwi8kRVDUG3GZkADzQSH6WF…>`_.
+The top entry, on the first page, with the date in the future, and empty list of attendees - is the next meeting.
+
+
+**How to join the meeting?**
+
+In the meeting notes `document <https://docs.google.com/document/d/18qKvEbfPszjsJJGJhwi8kRVDUG3GZkADzQSH6WF…>`_,
+on the top it says “to join, click the link”, click the link.
+
+
+**Do I need an invitation to join the meeting?**
+
+No, just join.
+
+
+**Do I need to create an account anywhere?**
+
+No, you can join without an account, and view/comment on the meeting doc without an account.
+
+
+**How do I add a topic to the agenda?**
+
+Add comments/suggestions on the meeting doc, and they will be accepted shortly after.
diff --git a/doc/index.rst b/doc/index.rst
index 3a83630..ea1027e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -8,5 +8,6 @@
dev_guide/index
classic_cli_manpage
+ contact
.. include:: ../README
--
To view, visit https://review.coreboot.org/c/flashrom/+/73822
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: flashrom
Gerrit-Branch: master
Gerrit-Change-Id: Ibfba6a59c5a945b4238d16e07a07584f94159568
Gerrit-Change-Number: 73822
Gerrit-PatchSet: 8
Gerrit-Owner: Thomas Heijligen <src(a)posteo.de>
Gerrit-Reviewer: Alexander Goncharov <chat(a)joursoir.net>
Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Edward O'Callaghan <quasisec(a)chromium.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-MessageType: merged
Anastasia Klimchuk has submitted this change. ( https://review.coreboot.org/c/flashrom/+/73359 )
(
9 is the latest approved patch-set.
No files were changed between the latest approved patch-set and the submitted one.
)Change subject: doc: Convert build documentation to sphinx
......................................................................
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(a)secunet.com>
Reviewed-on: https://review.coreboot.org/c/flashrom/+/73359
Reviewed-by: Alexander Goncharov <chat(a)joursoir.net>
Reviewed-by: Edward O'Callaghan <quasisec(a)chromium.org>
Reviewed-by: Anastasia Klimchuk <aklm(a)chromium.org>
Tested-by: build bot (Jenkins) <no-reply(a)coreboot.org>
---
D Documentation/building.md
M doc/conf.py
A doc/dev_guide/building_from_source.rst
A doc/dev_guide/index.rst
M doc/index.rst
5 files changed, 296 insertions(+), 148 deletions(-)
Approvals:
build bot (Jenkins): Verified
Edward O'Callaghan: Looks good to me, approved
Anastasia Klimchuk: Looks good to me, approved
Alexander Goncharov: Looks good to me, but someone else must approve
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/conf.py b/doc/conf.py
index 79d8aae..77aa29b 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -17,11 +17,19 @@
master_doc = 'index' # this is needed for old versions
-extensions = []
+extensions = [
+ 'sphinx.ext.todo'
+]
#templates_path = ['_templates']
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 -------------------------------------------------
diff --git a/doc/dev_guide/building_from_source.rst b/doc/dev_guide/building_from_source.rst
new file mode 100644
index 0000000..42a16f0
--- /dev/null
+++ b/doc/dev_guide/building_from_source.rst
@@ -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>
diff --git a/doc/dev_guide/index.rst b/doc/dev_guide/index.rst
new file mode 100644
index 0000000..9c6c0b1
--- /dev/null
+++ b/doc/dev_guide/index.rst
@@ -0,0 +1,7 @@
+Developers documentation
+========================
+
+.. toctree::
+ :maxdepth: 1
+
+ building_from_source
\ No newline at end of file
diff --git a/doc/index.rst b/doc/index.rst
index d309a03..3a83630 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -6,6 +6,7 @@
.. toctree::
:hidden:
+ dev_guide/index
classic_cli_manpage
.. include:: ../README
--
To view, visit https://review.coreboot.org/c/flashrom/+/73359
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: flashrom
Gerrit-Branch: master
Gerrit-Change-Id: I96771e98b313a6d26dd2be940ff37998d4124324
Gerrit-Change-Number: 73359
Gerrit-PatchSet: 12
Gerrit-Owner: Thomas Heijligen <src(a)posteo.de>
Gerrit-Reviewer: Alexander Goncharov <chat(a)joursoir.net>
Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Edward O'Callaghan <quasisec(a)chromium.org>
Gerrit-Reviewer: Peter Marheine <pmarheine(a)chromium.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-CC: Angel Pons <th3fanbus(a)gmail.com>
Gerrit-CC: Stefan Reinauer <stefan.reinauer(a)coreboot.org>
Gerrit-MessageType: merged
Anastasia Klimchuk has submitted this change. ( https://review.coreboot.org/c/flashrom/+/73439 )
(
4 is the latest approved patch-set.
No files were changed between the latest approved patch-set and the submitted one.
)Change subject: meson_cross: Introduce meson cross file for DJGPP/DOS
......................................................................
meson_cross: Introduce meson cross file for DJGPP/DOS
With `meson setup --cross-file meson_cross/i586_djgpp_dos.txt builddir`
you can build flashrom as DOS executable.
Change-Id: Iabda73942c1e64cd46604c78533982374f78e1a4
Signed-off-by: Thomas Heijligen <thomas.heijligen(a)secunet.com>
Reviewed-on: https://review.coreboot.org/c/flashrom/+/73439
Reviewed-by: Edward O'Callaghan <quasisec(a)chromium.org>
Reviewed-by: Anastasia Klimchuk <aklm(a)chromium.org>
Tested-by: build bot (Jenkins) <no-reply(a)coreboot.org>
---
A meson_cross/i586_djgpp_dos.txt
1 file changed, 46 insertions(+), 0 deletions(-)
Approvals:
build bot (Jenkins): Verified
Edward O'Callaghan: Looks good to me, approved
Anastasia Klimchuk: Looks good to me, approved
diff --git a/meson_cross/i586_djgpp_dos.txt b/meson_cross/i586_djgpp_dos.txt
new file mode 100644
index 0000000..66d5ed0
--- /dev/null
+++ b/meson_cross/i586_djgpp_dos.txt
@@ -0,0 +1,29 @@
+# This file is for cross compiling flashrom for DOS with DJGPP.
+#
+# Make sure the program names match your toolchain
+#
+# Make sure pkg-config can find your self compiles libpci
+# or add the path of your libpci.pc as 'pkg_config_libdir'
+# under [properies] below.
+
+[binaries]
+c = 'i586-pc-msdosdjgpp-gcc'
+ar = 'i586-pc-msdosdjgpp-ar'
+strip = 'i586-pc-msdosdjgpp-strip'
+pkgconfig = 'pkg-config'
+
+[host_machine]
+system = 'dos'
+cpu_family = 'x86'
+cpu = 'i586'
+endian = 'little'
+
+[built-in options]
+c_std = 'gnu99'
+default_library = 'static'
+
+[project options]
+tests = 'disabled'
+ich_descriptors_tool = 'disabled'
+
+[properties]
--
To view, visit https://review.coreboot.org/c/flashrom/+/73439
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings
Gerrit-Project: flashrom
Gerrit-Branch: master
Gerrit-Change-Id: Iabda73942c1e64cd46604c78533982374f78e1a4
Gerrit-Change-Number: 73439
Gerrit-PatchSet: 10
Gerrit-Owner: Thomas Heijligen <src(a)posteo.de>
Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org>
Gerrit-Reviewer: Edward O'Callaghan <quasisec(a)chromium.org>
Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org>
Gerrit-MessageType: merged