April 2023 - flashrom-gerrit - mail.coreboot.org

[S] Change in flashrom[refs/meta/config]: Review access change
by Anastasia Klimchuk (Code Review) April 28, 2023

April 28, 2023

Anastasia Klimchuk has uploaded this change for review. ( https://review.coreboot.org/c/flashrom/+/74694 ) Change subject: Review access change ...................................................................... Review access change Change-Id: I65c82a2c640638a9dbdd60f63996e63a618f04a1 --- M groups M project.config 2 files changed, 12 insertions(+), 0 deletions(-) git pull ssh://review.coreboot.org:29418/flashrom refs/changes/94/74694/1 diff --git a/groups b/groups index ca8045d..2b8df05 100644 --- a/groups +++ b/groups @@ -7,4 +7,5 @@ user:Th3Fanbus user/Angel Pons (Th3Fanbus) user:aklm user/Anastasia Klimchuk (aklm) user:dhendrix user/David Hendricks (dhendrix) +user:heijligen user/Thomas Heijligen (heijligen) user:jenkins user/build bot (Jenkins) (jenkins) diff --git a/project.config b/project.config index 8c30ea3..269a9ae 100644 --- a/project.config +++ b/project.config @@ -50,9 +50,11 @@ create = group user/Anastasia Klimchuk (aklm) create = group user/Angel Pons (Th3Fanbus) create = group user/David Hendricks (dhendrix) + create = group user/Thomas Heijligen (heijligen) delete = group user/Anastasia Klimchuk (aklm) delete = group user/Angel Pons (Th3Fanbus) delete = group user/David Hendricks (dhendrix) + delete = group user/Thomas Heijligen (heijligen) submit = group flashrom developers label-Code-Review = -2..+2 group flashrom developers label-Code-Review = -1..+2 group flashrom reviewers -- To view, visit https://review.coreboot.org/c/flashrom/+/74694 To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: refs/meta/config Gerrit-Change-Id: I65c82a2c640638a9dbdd60f63996e63a618f04a1 Gerrit-Change-Number: 74694 Gerrit-PatchSet: 1 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-MessageType: newchange

1 0

[M] Change in flashrom[master]: doc: Convert README to sphinx
by Anastasia Klimchuk (Code Review) April 28, 2023

April 28, 2023

Attention is currently required from: Thomas Heijligen, Stefan Reinauer, Alexander Goncharov. Anastasia Klimchuk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/74216 ) Change subject: doc: Convert README to sphinx ...................................................................... Patch Set 3: (1 comment) Patchset: PS3: This is ready! I rebased on the latest head and fixed the broken link. The end result is that README content gets generated into index.html (which is as expected right?), so there is no separate readme.html file. Thank you so much for review! This will be a home page on the new flashrom website. -- 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-Comment-Date: Fri, 28 Apr 2023 10:13:52 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No Gerrit-MessageType: comment

1 0

[M] Change in flashrom[master]: doc: Convert README to sphinx
by Anastasia Klimchuk (Code Review) April 28, 2023

April 28, 2023

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

1 0

[S] Change in flashrom[master]: doc: Add doc how to add docs
by Anastasia Klimchuk (Code Review) April 28, 2023

April 28, 2023

Attention is currently required from: Thomas Heijligen, Alexander Goncharov. Hello build bot (Jenkins), Thomas Heijligen, Alexander Goncharov, I'd like you to reexamine a change. Please visit https://review.coreboot.org/c/flashrom/+/74225 to look at the new patch set (#3). Change subject: doc: Add doc how to add docs ...................................................................... doc: Add doc how to add docs Change-Id: I356a286ad2f3334392efadda366b0ca0f8042752 Signed-off-by: Anastasia Klimchuk <aklm(a)chromium.org> --- A doc/how_to_add_docs.rst M doc/index.rst 2 files changed, 35 insertions(+), 0 deletions(-) git pull ssh://review.coreboot.org:29418/flashrom refs/changes/25/74225/3 -- To view, visit https://review.coreboot.org/c/flashrom/+/74225 To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: master Gerrit-Change-Id: I356a286ad2f3334392efadda366b0ca0f8042752 Gerrit-Change-Number: 74225 Gerrit-PatchSet: 3 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Alexander Goncharov <chat(a)joursoir.net> 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: Alexander Goncharov <chat(a)joursoir.net> Gerrit-MessageType: newpatchset

1 0

[S] Change in flashrom[master]: cli_classic: move version output outside of parsing
by Anastasia Klimchuk (Code Review) April 27, 2023

April 27, 2023

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

1 0

[S] Change in flashrom[master]: cli_classic: move usage output outside of parsing
by Anastasia Klimchuk (Code Review) April 27, 2023

April 27, 2023

Attention is currently required from: Edward O'Callaghan, Alexander Goncharov. Anastasia Klimchuk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/66534 ) Change subject: cli_classic: move usage output outside of parsing ...................................................................... Patch Set 2: Code-Review+2 (1 comment) Commit Message: https://review.coreboot.org/c/flashrom/+/66534/comment/a54aa68e_1404fc83 PS2, Line 17: `valgrind --leak-check=full --show-leak-kinds=all ./flashrom --flash-contents file --help` Ah, thank you for using valgrind! -- To view, visit https://review.coreboot.org/c/flashrom/+/66534 To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: master Gerrit-Change-Id: Ie1159b3efd8130fdc409a8908dc61102fa8b3fd1 Gerrit-Change-Number: 66534 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:48:35 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

1 0

[M] Change in flashrom[master]: cli_classic: move validation of incompatible options to one place
by Anastasia Klimchuk (Code Review) April 27, 2023

April 27, 2023

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

1 0

[M] Change in flashrom[master]: cli_classic: wrap options validation in function
by Anastasia Klimchuk (Code Review) April 27, 2023

April 27, 2023

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

1 0

[M] Change in flashrom[master]: doc: Add contact page
by Anastasia Klimchuk (Code Review) April 27, 2023

April 27, 2023

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

1 0

[L] Change in flashrom[master]: doc: Convert build documentation to sphinx
by Anastasia Klimchuk (Code Review) April 27, 2023

April 27, 2023

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

1 0