February 2024 - flashrom-gerrit

[XS] Change in flashrom[main]: serprog: clean up documentation
by Riku Viitanen (Code Review) 24 Feb '24

24 Feb '24

Attention is currently required from: Riku Viitanen. Hello Anastasia Klimchuk, build bot (Jenkins), I'd like you to reexamine a change. Please visit https://review.coreboot.org/c/flashrom/+/80499?usp=email to look at the new patch set (#2). The following approvals got outdated and were removed: Verified+1 by build bot (Jenkins) Change subject: serprog: clean up documentation ...................................................................... serprog: clean up documentation * serprog.h doesn't exist, so refer to .c source instead * in the doc, no other command has S_CMD_ prefix either Change-Id: Ic83e7fd80840f2db0b006935a964721da0388068 Signed-off-by: Riku Viitanen <riku.viitanen(a)protonmail.com> Reviewed-on: https://review.sourcearcade.org/c/flashprog/+/52 Reviewed-by: Nico Huber <nico.h(a)gmx.de> Tested-by: Nico Huber <nico.h(a)gmx.de> --- M Documentation/serprog-protocol.txt 1 file changed, 2 insertions(+), 2 deletions(-) git pull ssh://review.coreboot.org:29418/flashrom refs/changes/99/80499/2 -- To view, visit https://review.coreboot.org/c/flashrom/+/80499?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: Ic83e7fd80840f2db0b006935a964721da0388068 Gerrit-Change-Number: 80499 Gerrit-PatchSet: 2 Gerrit-Owner: Riku Viitanen <riku.viitanen(a)protonmail.com> Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-Attention: Riku Viitanen <riku.viitanen(a)protonmail.com> Gerrit-MessageType: newpatchset

1 0

[M] Change in flashrom[main]: doc: Add doc how to support flashrom project
by Anastasia Klimchuk (Code Review) 23 Feb '24

23 Feb '24

Attention is currently required from: Thomas Heijligen. Hello Thomas Heijligen, build bot (Jenkins), I'd like you to reexamine a change. Please visit https://review.coreboot.org/c/flashrom/+/80729?usp=email to look at the new patch set (#2). The following approvals got outdated and were removed: Verified+1 by build bot (Jenkins) Change subject: doc: Add doc how to support flashrom project ...................................................................... doc: Add doc how to support flashrom project Change-Id: I59a4f5978bc8ffa8ca3a3dc3f15c770ef5fcedce Signed-off-by: Anastasia Klimchuk <aklm(a)flashrom.org> --- M doc/contact.rst M doc/contrib_howtos/index.rst M doc/dev_guide/development_guide.rst A doc/how_to_support_flashrom.rst M doc/index.rst 5 files changed, 177 insertions(+), 2 deletions(-) git pull ssh://review.coreboot.org:29418/flashrom refs/changes/29/80729/2 -- To view, visit https://review.coreboot.org/c/flashrom/+/80729?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I59a4f5978bc8ffa8ca3a3dc3f15c770ef5fcedce Gerrit-Change-Number: 80729 Gerrit-PatchSet: 2 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.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-MessageType: newpatchset

1 0

[M] Change in flashrom[main]: doc: Add doc how to support flashrom project
by Anastasia Klimchuk (Code Review) 23 Feb '24

23 Feb '24

Anastasia Klimchuk has uploaded this change for review. ( https://review.coreboot.org/c/flashrom/+/80729?usp=email ) Change subject: doc: Add doc how to support flashrom project ...................................................................... doc: Add doc how to support flashrom project Change-Id: I59a4f5978bc8ffa8ca3a3dc3f15c770ef5fcedce Signed-off-by: Anastasia Klimchuk <aklm(a)flashrom.org> --- M doc/contact.rst M doc/contrib_howtos/index.rst M doc/dev_guide/development_guide.rst A doc/how_to_support_flashrom.rst M doc/index.rst 5 files changed, 176 insertions(+), 2 deletions(-) git pull ssh://review.coreboot.org:29418/flashrom refs/changes/29/80729/1 diff --git a/doc/contact.rst b/doc/contact.rst index 57a9390..79cdb91 100644 --- a/doc/contact.rst +++ b/doc/contact.rst @@ -33,8 +33,10 @@ 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). -Real time chats ---------------- +.. _real time channels: + +Real time channels +------------------ Flashrom has real time channels where you have the chance to talk to people being involved or interested in the project. Most of the discussion is about flashrom development, contributions, tech talk and user help. diff --git a/doc/contrib_howtos/index.rst b/doc/contrib_howtos/index.rst index b33482d..cb74e1c 100644 --- a/doc/contrib_howtos/index.rst +++ b/doc/contrib_howtos/index.rst @@ -8,3 +8,4 @@ how_to_mark_chip_tested how_to_add_unit_test ../how_to_add_docs + ../how_to_support_flashrom diff --git a/doc/dev_guide/development_guide.rst b/doc/dev_guide/development_guide.rst index 247a31a..0b64325 100644 --- a/doc/dev_guide/development_guide.rst +++ b/doc/dev_guide/development_guide.rst @@ -323,6 +323,8 @@ Note the search is not a replacement for Merge checklist, but it can help find candidates for merging. +.. _bugtracker: + Bugtracker ========== diff --git a/doc/how_to_support_flashrom.rst b/doc/how_to_support_flashrom.rst new file mode 100644 index 0000000..65aa2b9 --- /dev/null +++ b/doc/how_to_support_flashrom.rst @@ -0,0 +1,168 @@ +======================= +How to support flashrom +======================= + +Intro +========= + +This document is for people and companies who want to help flashrom, and it explains +various ways how to do this. + +There are lots of ways to help (as you can see below), whether you have little time or a lot, +whether you are a developer, a user or a company. +flashrom is a free open source software project, and all the contributions are publicly visible - +which means you get all the glory for your work, and you help the whole open source ecosystem. +Thank you! + +flashrom supports a huge variety of environments, platforms and hardware, and there is +no one person or one company on earth which has setup to test and maintain all of these +(and realistically, never will be). The only way we can maintain all of these, +is together as a community. + +To be aware of what's going on, subscribe to our :ref:`mailing list` and/or join our :ref:`real time channels`. + +Development +=========== + +Development, or in other words, sending patches to flashrom, is what probably comes to mind first +when you think about helping and contributing. And indeed, this is a great help, +and patches are always welcome. + +If your idea fits into one patch, you can just send it. If you have bigger plans in mind, +a large amount of work over a longer time frame, the best way is to start a topic on the mailing list. +This helps with planning, and also people in the community, whoever is interested, +will be able to support your effort. + +If you are new to flashrom development process, please start by reading :doc:`/dev_guide/development_guide`. +It's also useful to check `existing patches <https://review.coreboot.org/q/status:open+project:flashrom>`_ +for examples on how the dev process works. + +For some types of contributions we have more detailed guidelines, check the list :doc:`/contrib_howtos/index`. + +Code reviews +============ + +Did you know: code reviews are equally important as writing the code! + +For each patch, we need at least one reviewer, and often more than one. +Doing code reviews is highly appreciated and highly respected! +All reviewers' names are immortalised in git history together with authors names, +as "Reviewed-by" and "Signed-off-by" tags in a commit message (see example<link to this patch>). + +Code review involves carefully inspecting the patch in Gerrit, and adding comments if anything +is unclear/potential errors/issues/something missing etc. If you think the patch is ready, +you can vote on the patch. Every Gerrit user with a registered account can add comments to patches +and vote +1/-1. Note that if you vote -1, you need to add a comment explaining why you gave a negative vote, +and what specific big issues that you see with the patch. Negative vote is a stronger opinion, +and in most cases just adding comments is enough. + +The group of people who can fully approve the patch (i.e. vote +2, see :doc:`/about_flashrom/team`) +is limited, however every Gerrit user can do code reviews. This increases overall confidence +in the reviewed patch. Approving the patch is much easier when the code reviews are done well. + +You can check pending patches under review `in Gerrit <https://review.coreboot.org/q/status:open+project:flashrom>`_ +and help with code review if a patch looks useful, you understand what it is about, and want to have it submitted. + +Building and testing +==================== + +Given the large variety of environments and hardware that flashrom supports, +the question of building and testing flashrom is always relevant. +Try to build flashrom at head on your environment and if it doesn't build, +send a patch to fix (see :doc:`/dev_guide/development_guide`) or file a ticket in :ref:`bugtracker` +with as many details as possible. + +A special case of this is, the time when flashrom team is preparing the release. +The release candidate tag is announced on the mailing list, and it is a great help to try and build and test +a release candidate in whatever your environment is. Both positive and negative results are important, +and you are welcome to share the results, just don't forget to include environment details. +In case of issues, as always: patches are very very welcome. + +Documentation +============= + +You don't have to be a flashrom developer to add, update or review documentation. In fact, +lots of users' docs can greatly benefit from reviews by the users, who are supposed to read and use the docs. +Doc how to update the docs is here: :doc:`/how_to_add_docs` + +As for specific ideas: + +#. If there is an announcement on the mailing list about new doc under review, + have a look and you can join the review + +#. Help migrate information from `old website <https://wiki.flashrom.org/>`_ to `new website <https://www.flashrom.org/>`_. + The rule is, all useful docs need to be migrated but they should be reviewed. Concrete example, + there are docs for programmers, written a while ago. If you are using the programmer regularly + you can review the existing doc and help update it (if needed) and then the updated doc will + go to the new website. + +#. New documentation welcome. + +Mailing list +============ + +If you are not subscribed: please subscribe (see :ref:`mailing list`) so you can see what's going on. + +Oftentimes, mailing list has questions from flashrom users. If it so happens +that you maybe know what they are asking, or have ideas about it - you are welcome to respond! +This will be very helpful. + +Similarly, if there is a development discussion that makes sense to you and is relevant: please join the discussion. + +Mailing list is archived, and archives are public and searchable. Which means, +when you respond to the post you not only help that one person who is asking, +but you also help one hundred people in future, who have the same question and can search the answer on the list archives. + +Joining the team +================ + +If you have experience of flashrom development, good knowledge of some of the areas of flashrom code, +some time and motivation, you can consider joining the team, more info here (:doc:`/about_flashrom/team`). +Unlike the previous ideas, this means some *regular* time commitment (the amount of time +can be small or large, but it is regular). + +If you are not at this stage yet, but are considering this as a potential goal for the future, +check the :doc:`/about_flashrom/team` page for what it means. + +Special appeal for companies +============================ + +There are lots of companies that have their own forks of flashrom, and it would be a great help +if you could contribute back to the upstream project! + +Try to keep your fork as close as possible to upstream, do not diverge without a strong reason. +This makes it easier for you to downstream patches, and also makes it easier to contribute patches +from your fork upstream. As an end result, you will be exchanging code and knowledge with a large ecosystem +rather than hiding in your own corner. Working together we can achieve a higher quality bar, +which is better for the upstream project, and better for your fork. + +Consider the following ideas: + +#. Send upstream the bug fixes you found + +#. Add unit tests for the areas you are using actively + +#. Add new features or add support for new platforms/hardware, especially if you have that in your lab + and can reliably test and maintain + +#. Help with releases: if you have an automated test suite, run it on release candidates. + Build and test flashrom for the devices you have in the lab. + +#. If possible, allocate an engineer(s) to contribute to upstream project (and all their work + you can downstream straight away). Upstream early, upstream often: anything you can upstream sooner + will make your life easier in the future. + +#. Have someone subscribed to the mailing list and respond when the topic is relevant to you, + and you have a knowledge of questions or ideas how to help. + +#. On a long term, consider joining the :doc:`/about_flashrom/team`, pick something to maintain: + for example a programmer you are using often + +Outro +======== + +If you read all of the above and still unsure what to do, but actually want to help, +please don't be afraid to ask flashrom project lead directly (Anastasia Klimchuk, +and you can find email in Gerrit<link to this patch> or tag aklm on Discord (see :ref:`real time channels`). + +**Every bit of help matters and you can help make flashrom a better place. Thank you!** diff --git a/doc/index.rst b/doc/index.rst index 2fdf778..60c42b0 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -16,6 +16,7 @@ contact release_notes/index about_flashrom/index + how_to_support_flashrom how_to_add_docs documentation_license Old wiki website <https://wiki.flashrom.org/> -- To view, visit https://review.coreboot.org/c/flashrom/+/80729?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I59a4f5978bc8ffa8ca3a3dc3f15c770ef5fcedce Gerrit-Change-Number: 80729 Gerrit-PatchSet: 1 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-MessageType: newchange

1 0

[L] Change in flashrom[main]: Add initial CH347T SPI programmer
by Anastasia Klimchuk (Code Review) 23 Feb '24

23 Feb '24

Anastasia Klimchuk has abandoned this change. ( https://review.coreboot.org/c/flashrom/+/70529?usp=email ) Change subject: Add initial CH347T SPI programmer ...................................................................... Abandoned merged as CB:70573 -- To view, visit https://review.coreboot.org/c/flashrom/+/70529?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I6da5e308af76693e60308c8165349128e517e09a Gerrit-Change-Number: 70529 Gerrit-PatchSet: 9 Gerrit-Owner: qianfan <qianfanguijin(a)163.com> Gerrit-Reviewer: Angel Pons <angel.pons(a)9elements.com> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-CC: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-CC: Angel Pons <th3fanbus(a)gmail.com> Gerrit-CC: Stefan Reinauer <stefan.reinauer(a)coreboot.org> Gerrit-MessageType: abandon

1 0

[XS] Change in flashrom[main]: doc: Clarify that adding docs follows dev process and add into howtos
by Anastasia Klimchuk (Code Review) 23 Feb '24

23 Feb '24

Anastasia Klimchuk has submitted this change. ( https://review.coreboot.org/c/flashrom/+/80631?usp=email ) Change subject: doc: Clarify that adding docs follows dev process and add into howtos ...................................................................... doc: Clarify that adding docs follows dev process and add into howtos Also add link to "How to add new doc" into a collection of Contributors howtos. The doc stays in root of docs, and also in the main left-side menu on the website, so that it is very easy to discover. Everyone who has even the slightest motivation to update the docs, should be able to find instructions easily. Change-Id: I882de0614ab76b8e83b0fafa67296526fecd8a16 Signed-off-by: Anastasia Klimchuk <aklm(a)flashrom.org> Reviewed-on: https://review.coreboot.org/c/flashrom/+/80631 Tested-by: build bot (Jenkins) <no-reply(a)coreboot.org> Reviewed-by: Stefan Reinauer <stefan.reinauer(a)coreboot.org> --- M doc/contrib_howtos/index.rst M doc/how_to_add_docs.rst 2 files changed, 6 insertions(+), 0 deletions(-) Approvals: build bot (Jenkins): Verified Stefan Reinauer: Looks good to me, approved diff --git a/doc/contrib_howtos/index.rst b/doc/contrib_howtos/index.rst index 59326cd..b33482d 100644 --- a/doc/contrib_howtos/index.rst +++ b/doc/contrib_howtos/index.rst @@ -7,3 +7,4 @@ how_to_add_new_chip how_to_mark_chip_tested how_to_add_unit_test + ../how_to_add_docs diff --git a/doc/how_to_add_docs.rst b/doc/how_to_add_docs.rst index 0b32acb..ee99ce7 100644 --- a/doc/how_to_add_docs.rst +++ b/doc/how_to_add_docs.rst @@ -1,6 +1,11 @@ How to add or update docs ========================= +Documentation files live in ``/doc`` directory in the source tree, so +adding or updating documentation follows the same process as changing +the code. If you've never done it before, start by carefully +reading the :doc:`/dev_guide/development_guide`. + To add or update a documentation page, you need to create or modify an ``.rst`` file in the ``/doc`` directory and send a patch for review. -- To view, visit https://review.coreboot.org/c/flashrom/+/80631?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I882de0614ab76b8e83b0fafa67296526fecd8a16 Gerrit-Change-Number: 80631 Gerrit-PatchSet: 3 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org> 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-MessageType: merged

1 0

[XS] Change in flashrom[main]: Makefile: Fix version string for non-Git builds
by Anastasia Klimchuk (Code Review) 22 Feb '24

22 Feb '24

Attention is currently required from: Anton Samsonov, Thomas Heijligen. Anastasia Klimchuk has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/79152?usp=email ) Change subject: Makefile: Fix version string for non-Git builds ...................................................................... Patch Set 6: Code-Review+2 -- To view, visit https://review.coreboot.org/c/flashrom/+/79152?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I8694e618878823a9e96b1f2bcfa63f6c71d3c2ed Gerrit-Change-Number: 79152 Gerrit-PatchSet: 6 Gerrit-Owner: Anton Samsonov <devel(a)zxlab.ru> Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-CC: Angel Pons <th3fanbus(a)gmail.com> Gerrit-CC: Anton Samsonov <avscomputing(a)gmail.com> Gerrit-CC: Anton Samsonov <contact-launchpad(a)zxlab.ru> Gerrit-Attention: Thomas Heijligen <src(a)posteo.de> Gerrit-Attention: Anton Samsonov <devel(a)zxlab.ru> Gerrit-Comment-Date: Thu, 22 Feb 2024 09:56:54 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

1 0

[XS] Change in flashrom[main]: Makefile: Fix version string for non-Git builds
by Anton Samsonov (Code Review) 21 Feb '24

21 Feb '24

Attention is currently required from: Anastasia Klimchuk, Anton Samsonov, Thomas Heijligen. Anton Samsonov has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/79152?usp=email ) Change subject: Makefile: Fix version string for non-Git builds ...................................................................... Patch Set 6: (1 comment) Commit Message: https://review.coreboot.org/c/flashrom/+/79152/comment/a8cacba5_0f9cb20b : PS5, Line 7: non-Git builds > How do you get the repo without Git? This patch applies to standalone source trees produced by GitHub snapshot (“Download ZIP” form of repo cloning), as well as `git archive`, and perhaps future releases. In fact, meson.build already behaves as expected in both Git- and non-Git scenarios — I just mirrored this behavior to Makefile. -- To view, visit https://review.coreboot.org/c/flashrom/+/79152?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I8694e618878823a9e96b1f2bcfa63f6c71d3c2ed Gerrit-Change-Number: 79152 Gerrit-PatchSet: 6 Gerrit-Owner: Anton Samsonov <devel(a)zxlab.ru> Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-CC: Angel Pons <th3fanbus(a)gmail.com> Gerrit-CC: Anton Samsonov <avscomputing(a)gmail.com> Gerrit-CC: Anton Samsonov <contact-launchpad(a)zxlab.ru> Gerrit-Attention: Thomas Heijligen <src(a)posteo.de> Gerrit-Attention: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Attention: Anton Samsonov <devel(a)zxlab.ru> Gerrit-Comment-Date: Wed, 21 Feb 2024 17:57:48 +0000 Gerrit-HasComments: Yes Gerrit-Has-Labels: No Comment-In-Reply-To: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-MessageType: comment

1 0

[XS] Change in flashrom[main]: Makefile: Fix version string for non-Git builds
by Anton Samsonov (Code Review) 21 Feb '24

21 Feb '24

Attention is currently required from: Anastasia Klimchuk, Anton Samsonov, Thomas Heijligen. Hello Anastasia Klimchuk, Thomas Heijligen, build bot (Jenkins), I'd like you to reexamine a change. Please visit https://review.coreboot.org/c/flashrom/+/79152?usp=email to look at the new patch set (#6). The following approvals got outdated and were removed: Code-Review+1 by Anastasia Klimchuk, Verified+1 by build bot (Jenkins) Change subject: Makefile: Fix version string for non-Git builds ...................................................................... Makefile: Fix version string for non-Git builds Match the version string for `make` builds to that of `meson` builds from both Git- and non-Git (release or current snapshot) source trees. Change-Id: I8694e618878823a9e96b1f2bcfa63f6c71d3c2ed Signed-off-by: Anton Samsonov <devel(a)zxlab.ru> --- M Makefile 1 file changed, 3 insertions(+), 1 deletion(-) git pull ssh://review.coreboot.org:29418/flashrom refs/changes/52/79152/6 -- To view, visit https://review.coreboot.org/c/flashrom/+/79152?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I8694e618878823a9e96b1f2bcfa63f6c71d3c2ed Gerrit-Change-Number: 79152 Gerrit-PatchSet: 6 Gerrit-Owner: Anton Samsonov <devel(a)zxlab.ru> Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-CC: Angel Pons <th3fanbus(a)gmail.com> Gerrit-CC: Anton Samsonov <contact-launchpad(a)zxlab.ru> Gerrit-Attention: Thomas Heijligen <src(a)posteo.de> Gerrit-Attention: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Attention: Anton Samsonov <devel(a)zxlab.ru> Gerrit-MessageType: newpatchset

1 0

[M] Change in flashrom[main]: Makefile,meson.build: Add support for Sphinx versions prior to 4.x
by Anastasia Klimchuk (Code Review) 21 Feb '24

21 Feb '24

Anastasia Klimchuk has submitted this change. ( https://review.coreboot.org/c/flashrom/+/77778?usp=email ) Change subject: Makefile,meson.build: Add support for Sphinx versions prior to 4.x ...................................................................... Makefile,meson.build: Add support for Sphinx versions prior to 4.x As of version 3.x, `sphinx-build` outputs man pages to "8" directory instead of "man8" expected by Makefile and doc/meson.build. See: https://github.com/sphinx-doc/sphinx/issues/7996 https://github.com/sphinx-doc/sphinx/issues/9217 Current solution is to rename "8" to "man8" after documentation build. That enables successful build and installation, as well as dependency tracking at build-system level, but not on `sphinx-build` own level upon which `meson` build blindly relies. Change-Id: I9cd280551a1ba4d17edb2e857d56f80431b61e1b Signed-off-by: Anton Samsonov <devel(a)zxlab.ru> Reviewed-on: https://review.coreboot.org/c/flashrom/+/77778 Tested-by: build bot (Jenkins) <no-reply(a)coreboot.org> Reviewed-by: Anastasia Klimchuk <aklm(a)chromium.org> Reviewed-by: Peter Marheine <pmarheine(a)chromium.org> --- M Makefile M doc/meson.build A doc/sphinx-wrapper.sh 3 files changed, 51 insertions(+), 2 deletions(-) Approvals: Anastasia Klimchuk: Looks good to me, approved build bot (Jenkins): Verified Peter Marheine: Looks good to me, approved diff --git a/Makefile b/Makefile index 7b1312d..a36e575 100644 --- a/Makefile +++ b/Makefile @@ -228,6 +228,10 @@ CONFIG_LIBPCI_CFLAGS := $(call dependency_cflags, libpci) CONFIG_LIBPCI_LDFLAGS := $(call dependency_ldflags, libpci) +CONFIG_SPHINXBUILD_VERSION := +CONFIG_SPHINXBUILD_MAJOR := 0 + + # Determine the destination OS, architecture and endian # IMPORTANT: The following lines must be placed before TARGET_OS, ARCH or ENDIAN # is ever used (of course), but should come after any lines setting CC because @@ -958,6 +962,11 @@ OBJS = $(CHIP_OBJS) $(PROGRAMMER_OBJS) $(LIB_OBJS) +ifeq ($(HAS_SPHINXBUILD), yes) +override CONFIG_SPHINXBUILD_VERSION := $(shell $(SPHINXBUILD) --version | cut -d' ' -f2 ) +override CONFIG_SPHINXBUILD_MAJOR := $(shell echo "$(CONFIG_SPHINXBUILD_VERSION)" | cut -d'.' -f1 ) +endif + all: $(PROGRAM)$(EXEC_SUFFIX) $(call has_dependency, $(HAS_SPHINXBUILD), man8/$(PROGRAM).8) ifeq ($(ARCH), x86) @@ -1022,7 +1031,7 @@ echo "The following features are unavailable on your machine: $(UNSUPPORTED_FEATURES)" \ exit 1; \ fi - @echo "Checking for program \"sphinx-build\": $(HAS_SPHINXBUILD)" + @echo "Checking for program \"sphinx-build\": $(HAS_SPHINXBUILD) $(CONFIG_SPHINXBUILD_VERSION)" %.o: %.c | config $(CC) -MMD $(CFLAGS) $(CPPFLAGS) $(FLASHROM_CFLAGS) $(FEATURE_FLAGS) -D'FLASHROM_VERSION=$(VERSION)' -o $@ -c $< @@ -1035,8 +1044,18 @@ $(RANLIB) $@ man8/$(PROGRAM).8: doc/* +# When using sphinx-build prior to version 4.x, man pages are output +# to a directory named "8" instead of expected "man8". We fix that +# by renaming "8" to "man8" and creating symlink "8" pointing to "man8". @if [ "$(HAS_SPHINXBUILD)" = "yes" ]; then \ $(SPHINXBUILD) -Drelease=$(VERSION) -b man doc .; \ + if [ "$(CONFIG_SPHINXBUILD_MAJOR)" -lt 4 ]; then \ + if [ -d 8 -a ! -L 8 ]; then \ + rm -rf man8; \ + mv 8 man8; \ + ln -s man8 8; \ + fi \ + fi \ else \ echo "$(SPHINXBUILD) not found. Can't build man-page"; \ exit 1; \ diff --git a/doc/meson.build b/doc/meson.build index aca73d8..5bc57b9 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -1,5 +1,6 @@ sphinx = find_program('sphinx-build', native : true, required : get_option('man-pages').enabled() or get_option('documentation').enabled()) +sphinx_wrapper = meson.current_source_dir() / 'sphinx-wrapper.sh' man_pages = [ 'flashrom.8' @@ -14,7 +15,7 @@ custom_target( 'man-pages', - command : [sphinx, '-b', 'man', '-q', '-d', '@PRIVATE_DIR@', '-Drelease=' + flashrom_version,'@CURRENT_SOURCE_DIR@', '@OUTDIR@'], + command : [sphinx_wrapper, '@OUTDIR@', ' '.join(man_outputs), sphinx, '-b', 'man', '-q', '-d', '@PRIVATE_DIR@', '-Drelease=' + flashrom_version, '@CURRENT_SOURCE_DIR@', '@OUTDIR@'], build_always_stale : true, # sphinx handles rebuilds output : man_outputs, install : true, diff --git a/doc/sphinx-wrapper.sh b/doc/sphinx-wrapper.sh new file mode 100755 index 0000000..5569638 --- /dev/null +++ b/doc/sphinx-wrapper.sh @@ -0,0 +1,29 @@ +#!/bin/sh + +OUTPUT_HOME="$1" +MAN_OUTPUTS="$2" +SPHINXBUILD="$3" +shift 3 + +"${SPHINXBUILD}" "$@" || exit $? + +SPHINXBUILD_MAJOR="$("${SPHINXBUILD}" --version | cut -d' ' -f2 | cut -d'.' -f1)" +if [ "${SPHINXBUILD_MAJOR}" -ge 4 ]; then + exit 0 +fi + +# sphinx-build 3.x outputs man pages to "8" directory instead of expected "man8". +# The following block checks for "man8" (and other output paths in ${MAN_OUTPUTS}) +# and, if that is missing, but "8" dir exists instead, it renames "8" to "man8" +# and creates a symlink named "8" that points to "man8", so that anyone is happy +# during the rest of current build and subsequent builds as well. + +for MAN_OUTPUT in ${MAN_OUTPUTS}; do + PATH_TARGET="${OUTPUT_HOME}/${MAN_OUTPUT}" + PATH_ACTUAL="${OUTPUT_HOME}/${MAN_OUTPUT#man}" + if [ -d "${PATH_ACTUAL}" -a ! -L "${PATH_ACTUAL}" ]; then + rm -rf "${PATH_TARGET}" + mv "${PATH_ACTUAL}" "${PATH_TARGET}" + ln -s "${MAN_OUTPUT}" "${PATH_ACTUAL}" + fi +done -- To view, visit https://review.coreboot.org/c/flashrom/+/77778?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I9cd280551a1ba4d17edb2e857d56f80431b61e1b Gerrit-Change-Number: 77778 Gerrit-PatchSet: 8 Gerrit-Owner: Anton Samsonov <devel(a)zxlab.ru> Gerrit-Reviewer: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Reviewer: Peter Marheine <pmarheine(a)chromium.org> Gerrit-Reviewer: Thomas Heijligen <src(a)posteo.de> Gerrit-Reviewer: build bot (Jenkins) <no-reply(a)coreboot.org> Gerrit-CC: Anton Samsonov <avscomputing(a)gmail.com> Gerrit-CC: Stefan Reinauer <stefan.reinauer(a)coreboot.org> Gerrit-MessageType: merged

1 0

[XS] Change in flashrom[main]: doc: Clarify that adding docs follows dev process and add into howtos
by Stefan Reinauer (Code Review) 20 Feb '24

20 Feb '24

Attention is currently required from: Anastasia Klimchuk, Thomas Heijligen. Stefan Reinauer has posted comments on this change. ( https://review.coreboot.org/c/flashrom/+/80631?usp=email ) Change subject: doc: Clarify that adding docs follows dev process and add into howtos ...................................................................... Patch Set 2: Code-Review+2 -- To view, visit https://review.coreboot.org/c/flashrom/+/80631?usp=email To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings Gerrit-Project: flashrom Gerrit-Branch: main Gerrit-Change-Id: I882de0614ab76b8e83b0fafa67296526fecd8a16 Gerrit-Change-Number: 80631 Gerrit-PatchSet: 2 Gerrit-Owner: Anastasia Klimchuk <aklm(a)chromium.org> 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: Anastasia Klimchuk <aklm(a)chromium.org> Gerrit-Comment-Date: Tue, 20 Feb 2024 00:55:06 +0000 Gerrit-HasComments: No Gerrit-Has-Labels: Yes Gerrit-MessageType: comment

1 0

2024

2023

2022

2021

2020

2019

2018

2017

flashrom-gerrit February 2024