diff options
179 files changed, 15318 insertions, 7653 deletions
diff --git a/.github/workflows/devmanual-ci.yml b/.github/workflows/devmanual-ci.yml new file mode 100644 index 0000000..9d8e11f --- /dev/null +++ b/.github/workflows/devmanual-ci.yml @@ -0,0 +1,32 @@ +# Copyright 2021 Gentoo Authors +# Distributed under the terms of the MIT license +# or the CC-BY-SA-4.0 license (dual-licensed) + +name: Devmanual CI + +on: + push: + branches: [master] + pull_request: + branches: [master] + workflow_dispatch: + +jobs: + build: + runs-on: ubuntu-latest # no gentoo :( + steps: + - name: checkout + uses: actions/checkout@v2 + - name: install prerequisites + # librsvg2-bin for rsvg-convert + # xsltproc for xsltproc + # libxml2-utils for xmllint + # tidy for tidy + run: | + sudo apt-get -q -y update + sudo apt-get -q -y install librsvg2-bin xsltproc libxml2-utils \ + tidy fonts-open-sans + - name: make + run: make + - name: make check + run: make check @@ -1,2 +1,5 @@ *.html *.png +.depend +documents.js +eclass-reference/ @@ -1,252 +1,427 @@ -Creative Commons Legal Code +Attribution-ShareAlike 4.0 International -Attribution-ShareAlike 2.0 +======================================================================= - CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE - LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN - ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS - INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES - REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR - DAMAGES RESULTING FROM ITS USE. +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public License -THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE -COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY -COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS -AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. - -BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE -TO BE BOUND BY THE TERMS OF THIS LICENSE. THE LICENSOR GRANTS YOU THE -RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS -AND CONDITIONS. - -1. Definitions - - a. "Collective Work" means a work, such as a periodical issue, anthology - or encyclopedia, in which the Work in its entirety in unmodified form, - along with a number of other contributions, constituting separate and - independent works in themselves, are assembled into a collective - whole. A work that constitutes a Collective Work will not be - considered a Derivative Work (as defined below) for the purposes of - this License. - b. "Derivative Work" means a work based upon the Work or upon the Work - and other pre-existing works, such as a translation, musical - arrangement, dramatization, fictionalization, motion picture version, - sound recording, art reproduction, abridgment, condensation, or any - other form in which the Work may be recast, transformed, or adapted, - except that a work that constitutes a Collective Work will not be - considered a Derivative Work for the purpose of this License. For the - avoidance of doubt, where the Work is a musical composition or sound - recording, the synchronization of the Work in timed-relation with a - moving image ("synching") will be considered a Derivative Work for the - purpose of this License. - c. "Licensor" means the individual or entity that offers the Work under - the terms of this License. - d. "Original Author" means the individual or entity who created the Work. - e. "Work" means the copyrightable work of authorship offered under the - terms of this License. - f. "You" means an individual or entity exercising rights under this - License who has not previously violated the terms of this License with - respect to the Work, or who has received express permission from the - Licensor to exercise rights under this License despite a previous - violation. - g. "License Elements" means the following high-level license attributes - as selected by Licensor and indicated in the title of this License: - Attribution, ShareAlike. - -2. Fair Use Rights. Nothing in this license is intended to reduce, limit, -or restrict any rights arising from fair use, first sale or other -limitations on the exclusive rights of the copyright owner under copyright -law or other applicable laws. - -3. License Grant. Subject to the terms and conditions of this License, -Licensor hereby grants You a worldwide, royalty-free, non-exclusive, -perpetual (for the duration of the applicable copyright) license to -exercise the rights in the Work as stated below: - - a. to reproduce the Work, to incorporate the Work into one or more - Collective Works, and to reproduce the Work as incorporated in the - Collective Works; - b. to create and reproduce Derivative Works; - c. to distribute copies or phonorecords of, display publicly, perform - publicly, and perform publicly by means of a digital audio - transmission the Work including as incorporated in Collective Works; - d. to distribute copies or phonorecords of, display publicly, perform - publicly, and perform publicly by means of a digital audio - transmission Derivative Works. - e. For the avoidance of doubt, where the work is a musical composition: - - i. Performance Royalties Under Blanket Licenses. Licensor waives - the exclusive right to collect, whether individually or via a - performance rights society (e.g. ASCAP, BMI, SESAC), royalties - for the public performance or public digital performance (e.g. - webcast) of the Work. - ii. Mechanical Rights and Statutory Royalties. Licensor waives the - exclusive right to collect, whether individually or via a music - rights society or designated agent (e.g. Harry Fox Agency), - royalties for any phonorecord You create from the Work ("cover - version") and distribute, subject to the compulsory license - created by 17 USC Section 115 of the US Copyright Act (or the - equivalent in other jurisdictions). - - f. Webcasting Rights and Statutory Royalties. For the avoidance of doubt, - where the Work is a sound recording, Licensor waives the exclusive - right to collect, whether individually or via a performance-rights - society (e.g. SoundExchange), royalties for the public digital - performance (e.g. webcast) of the Work, subject to the compulsory - license created by 17 USC Section 114 of the US Copyright Act (or the - equivalent in other jurisdictions). - -The above rights may be exercised in all media and formats whether now -known or hereafter devised. The above rights include the right to make -such modifications as are technically necessary to exercise the rights in -other media and formats. All rights not expressly granted by Licensor are -hereby reserved. - -4. Restrictions. The license granted in Section 3 above is expressly made -subject to and limited by the following restrictions: - - a. You may distribute, publicly display, publicly perform, or publicly - digitally perform the Work only under the terms of this License, and - You must include a copy of, or the Uniform Resource Identifier for, - this License with every copy or phonorecord of the Work You - distribute, publicly display, publicly perform, or publicly digitally - perform. You may not offer or impose any terms on the Work that alter - or restrict the terms of this License or the recipients' exercise of - the rights granted hereunder. You may not sublicense the Work. You - must keep intact all notices that refer to this License and to the - disclaimer of warranties. You may not distribute, publicly display, - publicly perform, or publicly digitally perform the Work with any - technological measures that control access or use of the Work in a - manner inconsistent with the terms of this License Agreement. The - above applies to the Work as incorporated in a Collective Work, but - this does not require the Collective Work apart from the Work itself - to be made subject to the terms of this License. If You create a - Collective Work, upon notice from any Licensor You must, to the extent - practicable, remove from the Collective Work any reference to such - Licensor or the Original Author, as requested. If You create a - Derivative Work, upon notice from any Licensor You must, to the extent - practicable, remove from the Derivative Work any reference to such - Licensor or the Original Author, as requested. - b. You may distribute, publicly display, publicly perform, or publicly - digitally perform a Derivative Work only under the terms of this - License, a later version of this License with the same License - Elements as this License, or a Creative Commons iCommons license that - contains the same License Elements as this License (e.g. Attribution- - ShareAlike 2.0 Japan). You must include a copy of, or the Uniform - Resource Identifier for, this License or other license specified in - the previous sentence with every copy or phonorecord of each - Derivative Work You distribute, publicly display, publicly perform, or - publicly digitally perform. You may not offer or impose any terms on - the Derivative Works that alter or restrict the terms of this License - or the recipients' exercise of the rights granted hereunder, and You - must keep intact all notices that refer to this License and to the - disclaimer of warranties. You may not distribute, publicly display, - publicly perform, or publicly digitally perform the Derivative Work - with any technological measures that control access or use of the Work - in a manner inconsistent with the terms of this License Agreement. The - above applies to the Derivative Work as incorporated in a Collective - Work, but this does not require the Collective Work apart from the - Derivative Work itself to be made subject to the terms of this - License. - c. If you distribute, publicly display, publicly perform, or publicly - digitally perform the Work or any Derivative Works or Collective - Works, You must keep intact all copyright notices for the Work and - give the Original Author credit reasonable to the medium or means You - are utilizing by conveying the name (or pseudonym if applicable) of - the Original Author if supplied; the title of the Work if supplied; to - the extent reasonably practicable, the Uniform Resource Identifier, if - any, that Licensor specifies to be associated with the Work, unless - such URI does not refer to the copyright notice or licensing - information for the Work; and in the case of a Derivative Work, a - credit identifying the use of the Work in the Derivative Work (e.g., - "French translation of the Work by Original Author," or "Screenplay - based on original Work by Original Author"). Such credit may be - implemented in any reasonable manner; provided, however, that in the - case of a Derivative Work or Collective Work, at a minimum such credit - will appear where any other comparable authorship credit appears and - in a manner at least as prominent as such other comparable authorship - credit. - -5. Representations, Warranties and Disclaimer - -UNLESS OTHERWISE AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE -WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND -CONCERNING THE MATERIALS, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, -INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, -FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF -LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, -WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION -OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. - -6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE -LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR -ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES -ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS -BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -7. Termination - - a. This License and the rights granted hereunder will terminate - automatically upon any breach by You of the terms of this License. - Individuals or entities who have received Derivative Works or - Collective Works from You under this License, however, will not have - their licenses terminated provided such individuals or entities remain - in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 - will survive any termination of this License. - b. Subject to the above terms and conditions, the license granted here is - perpetual (for the duration of the applicable copyright in the Work). - Notwithstanding the above, Licensor reserves the right to release the - Work under different license terms or to stop distributing the Work at - any time; provided, however that any such election will not serve to - withdraw this License (or any other license that has been, or is - required to be, granted under the terms of this License), and this - License will continue in full force and effect unless terminated as - stated above. - -8. Miscellaneous - - a. Each time You distribute or publicly digitally perform the Work or a - Collective Work, the Licensor offers to the recipient a license to the - Work on the same terms and conditions as the license granted to You - under this License. - b. Each time You distribute or publicly digitally perform a Derivative - Work, Licensor offers to the recipient a license to the original Work - on the same terms and conditions as the license granted to You under - this License. - c. If any provision of this License is invalid or unenforceable under - applicable law, it shall not affect the validity or enforceability of - the remainder of the terms of this License, and without further action - by the parties to this agreement, such provision shall be reformed to - the minimum extent necessary to make such provision valid and - enforceable. - d. No term or provision of this License shall be deemed waived and no - breach consented to unless such waiver or consent shall be in writing - and signed by the party to be charged with such waiver or consent. - e. This License constitutes the entire agreement between the parties with - respect to the Work licensed here. There are no understandings, - agreements or representations with respect to the Work not specified - here. Licensor shall not be bound by any additional provisions that - may appear in any communication from You. This License may not be - modified without the mutual written agreement of the Licensor and You. - - - Creative Commons is not a party to this License, and makes no warranty - whatsoever in connection with the Work. Creative Commons will not be - liable to You or any party on any legal theory for any damages - whatsoever, including without limitation any general, special, - incidental or consequential damages arising in connection to this - license. Notwithstanding the foregoing two (2) sentences, if Creative - Commons has expressly identified itself as the Licensor hereunder, it - shall have all rights and obligations of Licensor. - - Except for the limited purpose of indicating to the public that the - Work is licensed under the CCPL, neither party will use the trademark - "Creative Commons" or any related trademark or logo of Creative - Commons without the prior written consent of Creative Commons. Any - permitted use will be in compliance with Creative Commons' - then-current trademark usage guidelines, as may be published on its - website or otherwise made available upon request from time to time. - - Creative Commons may be contacted at http://creativecommons.org/. +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + including for purposes of Section 3(b); and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. @@ -1,23 +1,125 @@ -text_files := $(shell find -name "text.xml" | sed -e "s/text.xml$$/index.html/") -image_files := $(shell find -name "*.svg" | sed -e "s/svg$$/png/") +# Run a single "find" pass to get a list of all files (with the .git +# directory excluded), then filter out what we need. +ALL_FILES := $(shell find . -name .git -prune -o -type f -print) +XMLS := $(filter %/text.xml,$(ALL_FILES)) +SVGS := $(filter %.svg,$(ALL_FILES)) +HTMLS := $(subst text.xml,index.html,$(XMLS)) +ECLASS_HTMLS := $(filter ./eclass-reference/%/index.html,$(ALL_FILES)) +IMAGES := $(patsubst %.svg,%.png,$(SVGS)) -all: prereq $(text_files) $(image_files) +CSS_FILES = devmanual.css offline.css +JS_FILES = search.js documents.js + +prefix = /usr/local/share +docdir = $(prefix)/doc/devmanual +htmldir = $(docdir) +DESTDIR = + +# Nonzero value disables external assets for offline browsing. +OFFLINE = 0 + +all: prereq validate build documents.js prereq: - @type -p convert &>/dev/null || { echo "media-gfx/imagemagick with corefonts, svg and truetype required" >&2; exit 1; }; \ - type -p xsltproc &>/dev/null || { echo "dev-libs/libxslt is required" >&2; exit 1; } + @type rsvg-convert >/dev/null 2>&1 || \ + { echo "gnome-base/librsvg required" >&2;\ + exit 1; } + @type xsltproc >/dev/null 2>&1 || \ + { echo "dev-libs/libxslt is with python required" >&2;\ + exit 1; } + @type xmllint >/dev/null 2>&1 || \ + { echo "dev-libs/libxml2 is required" >&2;\ + exit 1; } + @fc-list -q "Open Sans" || \ + { echo "media-fonts/open-sans is required" >&2;\ + exit 1; } + +build: $(HTMLS) $(IMAGES) -%index.html : %text.xml - xsltproc devbook.xsl $< > $@ +# We need to parse all the XMLs every time, not just the ones +# that are newer than the target. This is because each search +# document in devmanual gets a unique ID, which is used to +# quickly tie search matches to the corresponding documents. +documents.js: bin/build_search_documents.py $(XMLS) + @python3 bin/build_search_documents.py $(XMLS) > $@ && echo "$@ built" -# Someone should figure out a way to put this to the pattern -index.html : text.xml - xsltproc devbook.xsl $< > $@ +%.svg : %.dot + dot -T svg -o $@ $< %.png : %.svg - convert $< $@ + rsvg-convert --output=$@ $< + +# Secondary expansion allows us to use the automatic variable $@ in +# the prerequisites. +# +# We use the pattern %.html rather than the more-sensible %index.html +# because the latter doesn't match our top-level index.html target. +# +.SECONDEXPANSION: +%.html: $$(dir $$@)text.xml devbook.xsl xsl/*.xsl + xsltproc --param offline "$(OFFLINE)" devbook.xsl $< > $@ + +eclass-reference/text.xml: + @echo "*** Warning: No eclass documentation found." >&2 + @echo "Install app-doc/eclass-manpages and" >&2 + @echo "run bin/gen-eclass-html.sh before calling make." >&2 + @echo "Creating a placeholder index as fallback." >&2 + bin/gen-eclass-html.sh -n + +appendices/todo-list/index.html: $(XMLS) + +# Each HTML file must depend on its XML file with all its descendants +# (for the contents tree), all its ancestors (for breadcrumbs), and +# the previous and next documents (for backward and forward links). +# Generate the list of dependencies with XSLT, which appears to be a +# better tool for this than make. +.depend: $(XMLS) eclass-reference/text.xml depend.xsl devbook.xsl + @xsltproc depend.xsl $(XMLS) > $@ + +install: all + set -e; \ + for file in $(HTMLS) $(ECLASS_HTMLS) $(IMAGES); do \ + install -d "$(DESTDIR)$(htmldir)"/$${file%/*}; \ + install -m 644 $${file} "$(DESTDIR)$(htmldir)"/$${file}; \ + done + install -m 644 $(CSS_FILES) "$(DESTDIR)$(htmldir)"/ + if test $(OFFLINE) -eq 0; then \ + install -m 644 $(JS_FILES) "$(DESTDIR)$(htmldir)"/; \ + fi + +validate: devbook.rng + @xmllint --noout --quiet --relaxng $< $(XMLS) + @echo "xmllint validation successful" + +%.rng: %.rnc + trang $< $@ + sed -i -e '2s/^/<!-- Auto-generated from $<; do not edit! -->\n/' $@ + +# Run app-text/htmltidy on the output to detect mistakes. +# We have to loop through them because otherwise tidy won't +# tell you which file contains a mistake. +tidy: $(HTMLS) $(ECLASS_HTMLS) + @status=0; \ + for f in $^; do \ + output=$$(sed 's/href=""/href="index.html"/' $${f} \ + | tidy -q -errors --drop-empty-elements no 2>&1) \ + || { status=$$?; echo "Failed on $${f}:"; echo "$${output}"; }; \ + done; \ + exit $${status} + @echo "tidy validation successful" + +check: validate tidy + +dist: + COMMITDATE=$$(TZ=UTC git log -1 --pretty="format:%cd" \ + --date="format-local:%Y%m%d"); \ + TARBALL="devmanual-0_pre$${COMMITDATE}.tar.xz"; \ + echo "Creating tarball: $${TARBALL}"; \ + git archive --format=tar --prefix=devmanual/ HEAD | xz > $${TARBALL} clean: - @find . -name "*.png" -a \! -path "./icons/*" -exec rm -v {} + - @find . -name "index.html" -exec rm -v {} + + @rm -f $(HTMLS) $(IMAGES) documents.js .depend + +.PHONY: all prereq build install check validate tidy dist clean +-include .depend @@ -3,8 +3,8 @@ devmanual.gentoo.org Gentoo devmanual source -You can find the compiled version here: http://devmanual.gentoo.org +You can find the compiled version here: https://devmanual.gentoo.org -This document is licensed under [CC-BY-SA-2.0](License) +This document is licensed under [CC-BY-SA-4.0](LICENSE) -See also http://devmanual.gentoo.org/appendices/contributing/index.html +See also https://devmanual.gentoo.org/appendices/contributing/index.html diff --git a/appendices/common-problems/text.xml b/appendices/common-problems/text.xml index b0a7e58..87c21bb 100644 --- a/appendices/common-problems/text.xml +++ b/appendices/common-problems/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/common-problems/"> <chapter> <title>Common Problems</title> @@ -8,15 +8,16 @@ This page provides suggestions on how to handle various commonly seen errors and QA notices. </p> +</body> <section> <title>Handling QA Notices</title> <body> <p> -The <c>ebuild.sh</c> part of portage includes a number of checks for common +The <c>ebuild.sh</c> part of Portage includes a number of checks for common problems. These can result in a 'QA Notice' message being displayed. You must -not rely upon portage always generating these messages <d/> they are not a +not rely upon Portage always generating these messages <d/> they are not a substitute for proper testing and QA by developers. </p> @@ -24,9 +25,10 @@ substitute for proper testing and QA by developers. Some eclasses output messages in the same format. These are not covered here. </note> +</body> <subsection> -<title>QA Notice -- USE Flag foo not in IUSE</title> +<title>QA Notice: USE Flag foo not in IUSE</title> <body> <p> @@ -40,7 +42,7 @@ See <uri link="::ebuild-writing/variables/#IUSE"/> and </subsection> <subsection> -<title>QA Notice -- foo in global scope</title> +<title>QA Notice: foo in global scope</title> <body> <p> @@ -54,36 +56,29 @@ in use, there are various alternatives: <c>sed</c>, <c>awk</c>, <c>grep</c>, <c>egrep</c>, <c>cut</c> etc </dt> <dd> - <p> Usually when any of the above are used in global scope, it is to manipulate - a version or program name string. These should be avoided in favour of - pure <c>bash</c> constructs. The <c>versionator</c> eclass is often of use here. - See <uri link="::ebuild-writing/variables/#Version Formatting Issues"/>, - <c>man versionator.eclass</c> and <uri - link="::tools-reference/bash/#Bash Variable Manipulation"/>. - </p> + a version or program name string. These should be avoided in favour of pure + <c>bash</c> constructs. The built-in helpers of EAPI 7 are useful here. See + <uri link="::ebuild-writing/variables/#Version and Name Formatting Issues"/> + and <uri link="::tools-reference/bash/#Bash Variable Manipulation"/>. </dd> <dt> <c>has_version</c>, <c>best_version</c> </dt> <dd> - <p> Calls to either of these globally indicates a serious problem. You must <b>not</b> have metadata varying based upon system-dependent information <d/> see <uri link="::general-concepts/portage-cache/"/>. You should rewrite your ebuilds to correctly use dependencies. - </p> </dd> <dt> <c>python</c>, <c>perl</c> etc </dt> <dd> - <p> Ebuilds are <c>bash</c> scripts. Offloading anything you don't know how to do in <c>bash</c> onto another language is not acceptable <d/> if nothing else, because not all users will always have a full system when ebuilds are sourced. - </p> </dd> </dl> @@ -91,7 +86,7 @@ in use, there are various alternatives: </subsection> <subsection> -<title>QA Notice -- foo is setXid, dynamically linked and using lazy bindings</title> +<title>QA Notice: foo is setXid, dynamically linked and using lazy bindings</title> <body> <p> @@ -105,8 +100,8 @@ for security reasons. If this message is shown, you have a couple of options: linking. This solution is preferred. </li> <li> - Use <c>append-ldflags</c> (see <uri - link="ebuild-writing/functions/src_compile/build-environment/#Adding Additional Flags"/>) + Use <c>append-ldflags</c> (see + <uri link="::ebuild-writing/functions/src_compile/build-environment/#Adding Additional Flags"/>) to add <c>-Wl,-z,now</c>. This will affect <e>all</e> binaries installed, not just the setXid ones. </li> </ul> @@ -115,7 +110,7 @@ for security reasons. If this message is shown, you have a couple of options: </subsection> <subsection> -<title>QA Notice -- ECLASS foo inherited illegally</title> +<title>QA Notice: ECLASS foo inherited illegally</title> <body> <p> @@ -131,7 +126,7 @@ inheritance occurring. Most commonly: <ul> <li> - When unmerging a package which was installed using an old portage version that + When unmerging a package which was installed using an old Portage version that did not record inheritance. </li> <li> @@ -139,7 +134,7 @@ inheritance occurring. Most commonly: link="::general-concepts/overlay/#Overlay and Eclasses"/>. </li> <li> - When working with a stale portage cache. + When working with a stale Portage cache. </li> </ul> @@ -152,30 +147,6 @@ you see this notice locally. If you see this notice when working with a pure </body> </subsection> - -<todo> -from vapier: -TEXTREL's ... binary files which contain text relocations ... see -'prepstrip' for a full description unsafe files ... basically files that -are setid and writable by Other users i've added the following QA checks to -portage HEAD (no idea when they'll hit a release): Insecure RUNPATHs ... -binary files which have RUNPATH's encoded in them which are in +t -directories Executable stacks ... binary files whose stack is marked with -+x ... will bomb on amd64 for example -</todo> - -</body> -</section> - -<section> -<title>Handling <c>repoman</c> Messages</title> -<body> - -<todo> -write me -</todo> - -</body> </section> <section> @@ -214,36 +185,14 @@ ebuilds. </p> <p> -Access violations most commonly occur during the install phase. See -<c>src_install</c> and <uri link="::general-concepts/install-destinations/"/> -for discussion. -</p> - -<p> -Sometimes problems can also occur with packages attempting to write to -<c>${HOME}</c>. To get around this, it is usually sufficient to trick the build -system into using a safer location. For example, the <c>fluxbox</c> menu generator -tries to work in <c>${HOME}/.fluxbox</c> <d/> to get around this, the following is -used: -</p> - -<codesample lang="ebuild"> -ebegin "Creating a menu file (may take a while)" -mkdir -p "${T}/home/.fluxbox" || die "mkdir home failed" -MENUFILENAME="${S}/data/menu" MENUTITLE="Fluxbox ${PV}" \ - CHECKINIT="no. go away." HOME="${T}/home" \ - "${S}"/util/fluxbox-generate_menu -is -ds \ - || die "menu generation failed" -eend $? -</codesample> - -<p> -In this situation, providing a fake home directory is all that is needed. +Access violations most commonly occur during the install +phase. Sometimes it is possible to get around the sandbox violations +by tricking the build system into using a safer location. See +<c>src_install</c> and +<uri link="::general-concepts/install-destinations/"/> for discussion. </p> </body> </section> - -</body> </chapter> </guide> diff --git a/appendices/contributing/text.xml b/appendices/contributing/text.xml index e434511..de63f6d 100644 --- a/appendices/contributing/text.xml +++ b/appendices/contributing/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/contributing/"> <chapter> <title>Contributing to This Document</title> @@ -6,8 +6,12 @@ <body> <p> Contributions for this document are very welcome. Whether you've found a typo -or have written an entire new section, the best way to get in touch is via Bugzilla -at <uri link="https://bugs.gentoo.org">bugs.gentoo.org</uri>. +or have written an entire new section, the best way to get in touch is via +Bugzilla. Please look at the +<uri link="https://bugs.gentoo.org/buglist.cgi?product=Documentation;component=Devmanual;resolution=---"> +bug list</uri> and file a +<uri link="https://bugs.gentoo.org/enter_bug.cgi?product=Documentation;component=Devmanual;format=guided"> +new bug</uri>. </p> <p> @@ -18,54 +22,68 @@ not be discussed. </p> <p> -This document is licensed under the <uri link="http://creativecommons.org/licenses/by-sa/2.0/"> -Creative Commons Attribution-ShareAlike 2.0 License </uri>. If this is a problem, -don't submit anything. +This document is licensed under the +<uri link="https://creativecommons.org/licenses/by-sa/4.0/"> +Creative Commons Attribution-ShareAlike 4.0 International License</uri>. +If this is a problem, don't submit anything. </p> <p> This document is produced using the DevBook XML build system. You can download -a snapshot of the system as well as the relevant XML files from Subversion. You -can also view the XML of any page by replacing <c>index.html</c> with -<c>text.xml</c> in the URL. If you'd rather just work with plain text, that's +a snapshot of the system as well as the relevant XML files from Git, +see the <uri link="::appendices/contributing/#Where to find the sources"> +following section</uri>. If you'd rather just work with plain text, that's fine too <d/> the formatting can be easily done by someone else (meaning, us). </p> +</body> -<subsection> - <title>Where to find the sources</title> - <body> +<section> +<title>Where to find the sources</title> +<body> <p> - Currently, sources are hosted on <uri link="http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=summary">git.overlays.gentoo.org</uri>. For current Gentoo developers, - access is at <c>git+ssh://git@git.overlays.gentoo.org/proj/devmanual.git</c>. Non-developers - can clone the respository by typing <c>git clone git://git.overlays.gentoo.org/proj/devmanual.git</c>. - The sources are also hosted on <uri link="https://github.com/gentoo/devmanual.gentoo.org">GitHub</uri> for those who - perfer to submit patches using pull requests. +Currently, sources are hosted on +<uri link="https://gitweb.gentoo.org/proj/devmanual.git">git.gentoo.org</uri>. +For current Gentoo developers, access is at +<c>git+ssh://git@git.gentoo.org/proj/devmanual.git</c>. +Non-developers can clone the repository by typing +<c>git clone git://anongit.gentoo.org/proj/devmanual.git</c>. +The sources are also hosted on +<uri link="https://github.com/gentoo/devmanual">GitHub</uri> +for those who prefer to submit patches using pull requests. </p> <p> - To build the devmanual, simply run <c>make</c> in the top directory of the repository. - You need <c>xsltproc</c> (from <c>dev-libs/libxslt</c>) for the XML to HTML - conversion and optionally also <c>ImageMagick</c> for the SVG to PNG conversion - used in some of the figures throughout the document. +To build the devmanual, simply run <c>make</c> in the top directory of +the repository. You need <c>xsltproc</c> (from <c>dev-libs/libxslt</c>) +for the XML to HTML conversion, <c>xmllint</c> (from <c>dev-libs/libxml2</c>) +for validation, and <c>rsvg-convert</c> (from <c>gnome-base/librsvg</c>) for +the SVG to PNG conversion used in some of the figures throughout the document. +</p> + +<p> +To check if the document's XML is valid, run <c>make validate</c> in the +top-level directory, which will validate all XML files using <c>xmllint</c>. </p> - </body> -</subsection> </body> +</section> <section> <title>Quick Introduction to DevBook XML</title> <body> <p> -DevBook XML is heavily based on <uri link="http://www.gentoo.org/doc/en/xml-guide.xml"> -GuideXML</uri> and many tags are similar, if not the same. The main differences -occur in layout which are designed to make a large-scale publication easier -to produce and manage using a hierarchical tree system. Before starting off you -really should first examine the GuideXML guide in a reasonable amount of depth. +DevBook XML is heavily based on GuideXML and many tags are similar, if not +the same. The main differences occur in layout which are designed to make +a large-scale publication easier to produce and manage using a hierarchical +tree system. Before starting off you really should first examine the +<uri link="::appendices/devbook-guide/">DevBook XML guide</uri> in a reasonable +amount of depth. </p> +</body> + <subsection> <title>Differences from GuideXML</title> <body> @@ -75,40 +93,34 @@ really should first examine the GuideXML guide in a reasonable amount of depth. Indentation </dt> <dd> - <p> - Indent when needed <d/> you should not indent any section flow elements such as - <c><subsection></c> but do indent tables, lists and definition lists. - Do <e>not</e> indent text in ordinary paragraph blocks. - </p> + Indent when needed <d/> you should not indent any section flow elements + such as <c><subsection></c> but do indent tables, lists and + definition lists. Do <e>not</e> indent text in ordinary paragraph blocks. </dd> <dt> Code Samples </dt> <dd> - <p> - You can use the normal GuideXML tag <c><pre></c> when you need no syntax - highlighting. When you need syntax highlighting use the <c><codesample></c> - tag along with a <c>lang</c> attribute <d/> usually you want this to be set to - <c>ebuild</c> to syntax highlight ebuild code snippets. - </p> + You can use the normal GuideXML tag <c><pre></c> when you need + no syntax highlighting. When you need syntax highlighting use the + <c><codesample></c> tag along with a <c>lang</c> attribute <d/> + usually you want this to be set to <c>ebuild</c> to syntax highlight ebuild + code snippets. </dd> <dt> Hierarchy </dt> <dd> - <p> - The whole document is organized as a tree. Each directory can contain one - document. Each document can inherit multiple sub-documents using the - <c><include></c> flag. You <b>must</b> ensure that the <c>self</c> tag - in each document correctly points to the relative path of the document from - the root node so that the tree-walking algorithms work correctly. - </p> + The whole document is organized as a tree. Each directory can contain + one document. Each document can inherit multiple sub-documents using the + <c><include></c> flag. You <b>must</b> ensure that the <c>self</c> + tag in each document correctly points to the relative path of the document + from the root node so that the tree-walking algorithms work correctly. </dd> </dl> </body> </subsection> -</body> </section> <section> @@ -127,16 +139,9 @@ really should first examine the GuideXML guide in a reasonable amount of depth. This is not a formal document. The writing style is intended to be professional but readable. </li> - <li> - When using in-sentence hyphens as punctuation <d/> like this <d/> use a space, - followed by the <c><d/></c> tag. The build system will automatically turn - this into a proper Unicode long dash. - </li> </ul> </body> </section> </chapter> - </guide> - diff --git a/appendices/contributors/text.xml b/appendices/contributors/text.xml index 21f8442..06a6e0c 100644 --- a/appendices/contributors/text.xml +++ b/appendices/contributors/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/contributors/"> <chapter> <title>Contributions</title> @@ -13,63 +13,65 @@ This page lists the contributions to the Gentoo Development Guide: Main Content </author> <author name="Grant Goodyear" email="g2boojum@gentoo.org"> - <uri link="::tools-reference/cat/#Here Documents"/>, + <uri link="::tools-reference/cat/#Here Documents"/> </author> <author name="Aaron Walker" email="ka0ttic@gentoo.org"> - <uri link="::tasks-reference/completion"/>, - <uri link="::eclass-reference/subversion.eclass">subversion.eclass</uri> + <uri link="::tasks-reference/completion/"/> </author> <author name="Robert Coie" email="rac@gentoo.org"> - <uri link="::appendices/editor-configuration/xemacs"/> + <uri link="::appendices/editor-configuration/xemacs/"/> </author> <author name="Tom Martin" email="slarti@gentoo.org"> - <uri link="::appendices/editor-configuration/emacs"/>, - <uri link="::ebuild-writing/functions/src_unpack/svn-sources"/>, + <uri link="::appendices/editor-configuration/emacs/"/>, <uri link="::general-concepts/use-flags/#Conflicting USE Flags"/> </author> <author name="Paul Varner" email="fuzzyray@gentoo.org"> - <uri link="::ebuild-writing/functions/src_unpack/rpm-sources"/> + <uri link="::ebuild-writing/functions/src_unpack/rpm-sources/"/> </author> <author name="Ilya Volynets-Evenbakh" email="iluxa@gentoo.org"> <uri link="::archs/mips/#MIPS ABIs"/> </author> <author name="Diego Pettenò" email="flameeyes@gentoo.org"> - <uri link="::tasks-reference/pam"/>, + <uri link="::tasks-reference/pam/"/>, <uri link="::general-concepts/autotools/#aclocal and m4 Files"/> </author> <author name="Fernando J. Pereda" email="ferdy@gentoo.org"> - <uri link="::archs/alpha"/> + <uri link="::archs/alpha/"/> </author> <author name="Simon Stelling" email="blubb@gentoo.org"> - <uri link="::archs/amd64"/> + <uri link="::archs/amd64/"/> </author> <author name="Alin Dobre" email="alin@gentoo.org"> - <uri link="::tools-reference/echo"/> + <uri link="::tools-reference/echo/"/> </author> +<!-- Contributions above this line were to the original (reStructuredText) + version, so they won't appear in the commit history --> <author name="Joseph Jezak" email="josejx@gentoo.org"> - <uri link="::archs/ppc"/> + <uri link="::archs/ppc/"/> </author> -<author name="Tim Yamin" email="plasm@roo.me.uk"> - XSL Stylesheets, previous maintainer +<author name="Ursula Maplehurst" email="plasm@roo.me.uk"> + Previous maintainer (XSL Stylesheets, legacy Developer Handbook content) </author> <author name="Mark Loeser" email="halcy0n@gentoo.org"> - XSL Stylesheets, current maintainer + XSL Stylesheets, previous maintainer </author> <author name="Petteri Räty" email="betelgeuse@gentoo.org"> -<uri link="::ebuild-writing"/>, -<uri link="::eclass-writing"/>, -<uri link="::general-concepts/dependencies"/>, +<uri link="::ebuild-writing/"/>, +<uri link="::eclass-writing/"/>, +<uri link="::general-concepts/dependencies/"/>, Misc </author> <author name="Ulrich Müller" email="ulm@gentoo.org"> - <uri link="::ebuild-writing"/>, - <uri link="::appendices/editor-configuration/emacs"/>, - <uri link="::general-concepts/licenses/"/>, + <uri link="::quickstart/"/>, <uri link="::general-concepts/virtuals/"/>, - <uri link="::ebuild-writing/eapi/"/> + <uri link="::ebuild-writing/"/>, + <uri link="::ebuild-maintenance/"/>, + <uri link="::appendices/editor-configuration/emacs/"/>, + <uri link="::appendices/devbook-guide/"/>, + DTD, XSL stylesheet, eclass conversion </author> <author name="Mike Pagano" email="mpagano@gentoo.org"> - <uri link="::general-concepts/news"/> + <uri link="::general-concepts/news/"/> </author> <author name="Markus Meier" email="maekke@gentoo.org"> Misc @@ -77,7 +79,56 @@ Misc <author name="Markos Chandras" email="hwoarang@gentoo.org"> Misc </author> - +<author name="Xavier Neys" email="neysx@gentoo.org"> + <uri link="::appendices/devbook-guide/">GuideXML guide</uri> +</author> +<author name="Daniel Robbins" email="drobbins@gentoo.org"> + <uri link="::appendices/devbook-guide/">GuideXML guide</uri> +</author> +<author name="Jeremy Olexa" email="darkside@gentoo.org"> + <uri link="::general-concepts/use-flags/"/> +</author> +<author name="Julian Ospald" email="hasufell@gentoo.org"> + <uri link="::ebuild-writing/common-mistakes/"/>, + <uri link="::tools-reference/find/"/> +</author> +<author name="Alexandre Rostovtsev" email="tetromino@gentoo.org"> + <uri link="::general-concepts/slotting/"/> +</author> +<author name="Göktürk Yüksek" email="gokturk@gentoo.org"> + <uri link="::general-concepts/projects/"/>, + <uri link="::ebuild-writing/variables/"/>, + <uri link="::ebuild-writing/misc-files/metadata/"/>, + <uri link="::eclass-writing/"/>, + <uri link="::appendices/devbook-guide/"/>, + search functionality +</author> +<author name="Michael Orlitzky" email="mjo@gentoo.org"> + <uri link="::ebuild-writing/users-and-groups/"/>, + <uri link="::eclass-writing/"/> +</author> +<author name="Michał Górny" email="mgorny@gentoo.org"> + <uri link="::general-concepts/"/>, + <uri link="::ebuild-writing/"/>, + <!-- The following is 700+ lines, so keep it as a separate entry --> + <uri link="::ebuild-writing/eapi/#EAPI 8"/>, + <uri link="::ebuild-maintenance/"/> +</author> +<author name="Brian Evans" email="grknight@gentoo.org"> + <uri link="::ebuild-writing/eapi/"/>, + <uri link="::ebuild-writing/variables/"/>, + <uri link="::ebuild-writing/functions/src_prepare/epatch/"/> +</author> +<author name="Lucas Ramage" email="ramage.lucas@protonmail.com"> + Search functionality +</author> +<author name="Mike Frysinger" email="vapier@gentoo.org"> + <uri link="::ebuild-writing/misc-files/patches/#Clean Patch Howto"/> +</author> +<author name="Sam James" email="sam@gentoo.org"> + <uri link="::eclass-writing/"/>, + <uri link="::keywording/"/> +</author> </authors> </body> diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml new file mode 100644 index 0000000..8301b0a --- /dev/null +++ b/appendices/devbook-guide/text.xml @@ -0,0 +1,710 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="appendices/devbook-guide/"> +<chapter> +<title>Gentoo DevBook XML Guide</title> + +<section> +<title>DevBook XML design goals</title> +<body> + +<p> +The DevBook XML syntax is lightweight yet expressive, so that it is easy to +learn yet also provides all the features we need for the creation of web +documentation. The number of tags is kept to a minimum <d/> just those we need. +This makes it easy to transform DevBook XML into other formats, such as DocBook +XML/SGML or web-ready HTML. +</p> + +<p> +The goal is to make it easy to <e>create</e> and <e>transform</e> DevBook XML +documents. +</p> + +</body> +</section> + +<section> +<title>Basic structure</title> +<body> + +<p> +Let's start learning the DevBook XML syntax. We'll start with the initial tags +used in a DevBook XML document: +</p> + +<codesample lang="sgml"><!-- The initial part of a DevBook XML document --> +<?xml version="1.0" encoding="UTF-8"?> +<guide self="appendices/devbook-guide/"> +<chapter> +<title>Gentoo DevBook XML Guide</title> +</codesample> + +<p> +On the first lines, we see the requisite tag that identifies this as an XML +document. Next, there's a <c><guide></c> tag <d/> the entire document is +enclosed within a <c><guide> </guide></c> pair. Its <c>self</c> +attribute must point to the relative path of the document from the root node; +in the example above the path is <c>appendices/devbook-guide/</c>. An exception +is the root node itself, which has <c><guide root="true"></c> instead. +</p> + +<p> +Next, there is a <c><chapter></c> tag. Every document must have exactly +one chapter. Its <c><title></c> is used to set the title for the entire +document. +</p> + +<p> +All tags must be closed of course, so the document ends with: +</p> + +<codesample lang="sgml"> +</chapter> +</guide> +</codesample> + +</body> + +<subsection> +<title>Sections and subsections</title> +<body> + +<p> +Once the initial tags have been specified, you're ready to start adding the +structural elements of the document. Chapters are divided into sections; +each section can hold zero or more subsections, which can contain zero or more +subsubsections. Section, subsection and subsubsection elements must have a +title. Here's an example section with a single subsection, consisting of a +paragraph: +</p> + +<codesample lang="sgml"><!-- Minimal DevBook example --> +<section> +<title>This is my section</title> +<subsection> +<title>This is subsection one of my section</title> +<body> + +<p> +This is the actual text content of my subsection. +</p> + +</body> +</subsection> +</section> +</codesample> + +<p> +Above, I set the section title by adding a child <c><title></c> element +to the <c><section></c> element. Then, I created a subsection by adding +a <c><subsection></c> element. If you look inside the +<c><subsection></c> element, you'll see that it has two child elements +<d/> a <c><title></c> and a <c><body></c>. While the +<c><title></c> is nothing new, the <c><body></c> is <d/> +it contains the actual text content of this particular subsection. We'll look +at the tags that are allowed inside a <c><body></c> element in a bit. +</p> + +<note> +The <c><chapter></c>, <c><section></c>, <c><subsection></c> +and <c><subsubsection></c> elements contain a <c><body></c> and/or +any number of section elements of the next lower level. Skipping of levels is +not allowed, e.g., a subsection cannot be directly below a chapter. +</note> + +</body> +</subsection> +<subsection> +<title>Including sub-documents</title> +<body> + +<p> +The manual is organized as a tree. Each directory contains one document, which +can include multiple sub-documents using the <c><include href="foo/"/></c> +tag. Note that the trailing slash in the <c>href</c> value is mandatory. +</p> + +<p> +A table of contents can be generated with <c><contentsTree></c>. +Typically, this tag would be the only element in its own section body, as in +the following example: +</p> + +<codesample lang="sgml"> +<section> +<title>Contents</title> +<body> +<contentsTree/> +</body> +</section> +</codesample> + +</body> +</subsection> +<subsection> +<title>An example <body></title> +<body> + +<p> +Now, it's time to learn how to mark up actual content. Here's the XML code for +an example <c><body></c> element: +</p> + +<codesample lang="sgml"><!-- Example of a body element --> +<p> +This is a paragraph. <c>/etc/passwd</c> is a file. +<uri>https://www.gentoo.org/</uri> is my favorite website. +Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. +</p> + +<pre> +This is text output or code. +# this is user input +</pre> + +<codesample lang="sgml"> +Make HTML/XML easier to read by using selective emphasis: +&lt;foo&gt;bar&lt;/foo&gt; +</codesample> + +<note> +This is a note. +</note> + +<important> +This is important. +</important> + +<warning> +This is a warning. +</warning> + +<todo> +Text inside a <c>todo</c> element will appear in the +<uri link="::appendices/todo-list/"/>. +</todo> +</codesample> + +<p> +Now, here's how the <c><body></c> element above is rendered: +</p> + +<p> +This is a paragraph. <c>/etc/passwd</c> is a file. +<uri>https://www.gentoo.org/</uri> is my favorite web site. +Type <c>ls</c> if you feel like it. I <e>really</e> want to go to sleep now. +</p> + +<pre> +This is text output or code. +# this is user input +</pre> + +<codesample lang="sgml"> +Make HTML/XML easier to read by using selective emphasis: +<foo>bar</foo> +</codesample> + +<note> +This is a note. +</note> + +<important> +This is important. +</important> + +<warning> +This is a warning. +</warning> + +<todo> +Text inside a <c>todo</c> element will appear in the +<uri link="::appendices/todo-list/"/>. +</todo> + +</body> +</subsection> +</section> + +<section> +<title>Body elements</title> +<body> + +<p> +We introduced a lot of new tags in the previous section <d/> here's what you +need to know. The <c><p></c> (paragraph), <c><pre></c> +(preformatted block), <c><codesample></c> (code block), +<c><note></c>, <c><important></c>, <c><warning></c> and +<c><todo></c> tags all can contain one or more lines of text. +Besides the <c><figure></c>, <c><table></c>, <c><ul></c>, +<c><ol></c> and <c><dl></c> elements (which we'll cover in just +a bit), these are the only tags that should appear immediately inside a +<c><body></c> element. Another thing <d/> these tags <e>should not</e> +be stacked <d/> in other words, don't put a <c><note></c> element inside +a <c><p></c> element. As you might guess, the <c><pre></c> and +<c><codesample></c> elements preserve their whitespace exactly, making +them well-suited for code excerpts: +</p> + +<codesample lang="sgml"><!-- Named <pre> --> +<pre> +# uptime +16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25 +</pre> +</codesample> + +</body> + +<subsection> +<title>Code samples and colour-coding</title> +<body> + +<p> +The <c><pre></c> tag does not support any syntax highlighting. When you +need syntax highlighting, use the <c><codesample></c> tag along with a +<c>lang</c> attribute <d/> usually you want this to be set to <c>"ebuild"</c> +to syntax highlight ebuild code snippets. Currently, the following languages +are supported: +</p> + +<ul> + <li>c</li> + <li>ebuild</li> + <li>make</li> + <li>m4</li> + <li>sgml</li> +</ul> + +<note> +Remember that all leading and trailing spaces, and line breaks in +<c><codesample></c> blocks will appear in the displayed html page. +</note> + +<p> +Sample <c><codesample lang="c"></c> block: +</p> + +<codesample lang="c"> +#include <stdio.h> + +main() +{ + /* This is a comment */ + printf("Hello, world!\n"); +} +</codesample> + +<p> +You can also specify <c>numbering="lines"</c> to enable line numbering, as in +the following example: +</p> + +<codesample lang="ebuild" numbering="lines"> +# Copyright 1999-2021 Gentoo Authors +# Distributed under the terms of the GNU General Public License v2 + +EAPI=7 + +DESCRIPTION="MicroGnuEmacs, a port from the BSDs" +HOMEPAGE="https://homepage.boetes.org/software/mg/" +SRC_URI="https://github.com/hboetes/${PN}/archive/${PV}.tar.gz -> ${P}.tar.gz" + +LICENSE="public-domain" +SLOT="0" +KEYWORDS="alpha amd64 arm hppa ppc ~ppc64 sparc x86" + +RDEPEND="sys-libs/ncurses:0= + >=dev-libs/libbsd-0.7.0" +DEPEND="${RDEPEND}" +BDEPEND="virtual/pkgconfig" + +src_install() { + dobin mg + doman mg.1 + dodoc README tutorial +} +</codesample> + +</body> +</subsection> +<subsection> +<title>Figures</title> +<body> + +<p> +Here's how to insert a figure into a document <d/> <c><figure +link="mygfx.png" short="my picture" caption="my favorite picture of all +time"/></c>. The <c>link</c> attribute points to the actual graphic image, +the <c>short</c> attribute specifies a short description (currently used for +the image's HTML <c>alt</c> attribute), and a caption. Not too difficult +:) We also support the standard HTML-style <img src="foo.gif"/> tag +for adding images without captions, borders, etc. +</p> + +</body> +</subsection> +<subsection> +<title>Tables</title> +<body> + +<p> +DevBook XML supports a simplified table syntax similar to that of HTML. To start +a table, use a <c><table></c> tag. Start a row with a <c><tr></c> +tag. However, for inserting actual table data, we <e>don't</e> support the HTML +<td> tag; instead, use the <c><th></c> if you are inserting a +header, and <c><ti></c> if you are inserting a normal informational +block. You can use a <c><th></c> anywhere you can use a <c><ti></c> +<d/> there's no requirement that <c><th></c> elements appear only in the +first row. +</p> + +<p> +Besides, both table headers (<c><th></c>) and table items +(<c><ti></c>) accept the <c>colspan</c> and <c>rowspan</c> attributes to +span their content across rows, columns or both. +</p> + +<p> +Furthermore, table cells (<c><ti></c> & <c><th></c>) can be +right-aligned, left-aligned or centered with the <c>align</c> attribute. +</p> + +<table> +<tr> + <th align="center" colspan="4">This title spans 4 columns</th> +</tr> +<tr> + <th rowspan="6">This title spans 6 rows</th> + <ti>Item A1</ti> + <ti>Item A2</ti> + <ti>Item A3</ti> +</tr> +<tr> + <ti align="center">Item B1</ti> + <th colspan="2" rowspan="2" align="right">Blocky 2x2 title</th> +</tr> +<tr> + <ti align="right">Item C1</ti> +</tr> +<tr> + <ti colspan="3" align="center">Item D1..D3</ti> +</tr> +<tr> + <ti rowspan="2">Item E1..F1</ti> + <ti colspan="2" align="right">Item E2..E3</ti> +</tr> +<tr> + <ti colspan="2" align="right">Item F2..F3</ti> +</tr> +</table> + +</body> +</subsection> +<subsection> +<title>Lists</title> +<body> + +<p> +To create ordered or unordered lists, simply use the XHTML-style +<c><ol></c>, <c><ul></c> and <c><li></c> tags. Lists may only +appear inside the <c><body></c> and <c><li></c> tags which means +that you can have lists inside lists. Don't forget that you are writing XML and +that you must close all tags including list items unlike in HTML. +</p> + +<p> +Definition lists (<c><dl></c>) are also supported. Please note that +the definition term tag (<c><dt></c>) does not accept any other block +level tag such as paragraphs or admonitions. A definition list comprises: +</p> + +<dl> + <dt><c><dl></c></dt> + <dd>A <b>D</b>efinition <b>L</b>ist Tag containing</dd> + <dt><c><dt></c></dt> + <dd><b>D</b>efinition <b>T</b>erm Tags</dd> + <dt><c><dd></c></dt> + <dd>and <b>D</b>efinition <b>D</b>ata Tags.</dd> +</dl> + +<p> +The following example copied from +<uri link="https://www.w3.org/TR/REC-html40/struct/lists.html">w3.org</uri> +shows that lists may also be nested and different list types may be used +together: +</p> + +<dl> + <dt>The ingredients:</dt> + <dd> + <ul> + <li>100 g flour</li> + <li>10 g sugar</li> + <li>1 cup water</li> + <li>2 eggs</li> + <li>salt, pepper</li> + </ul> + </dd> + <dt>The procedure:</dt> + <dd> + <ol> + <li>Mix dry ingredients thoroughly.</li> + <li>Pour in wet ingredients.</li> + <li>Mix for 10 minutes.</li> + <li>Bake for one hour at 300 degrees.</li> + </ol> + </dd> + <dt>Notes:</dt> + <dd>The recipe may be improved by adding raisins.</dd> +</dl> + +</body> +</subsection> +</section> + +<section> +<title>Inline elements</title> +<subsection> +<title><c>, <b>, <e>, <sub> and <sup></title> +<body> + +<p> +The <c><c></c> element is used to mark up a <e>command</e> or <e>user +input</e>. Think of <c><c></c> as a way to alert the reader to something +that they can type in that will perform some kind of action. For example, +all the XML tags displayed in this document are enclosed in a <c><c></c> +element because they represent something that the user could type in that is +not a path. By using <c><c></c> elements, you'll help your readers +quickly identify commands that they need to type in. Also, because +<c><c></c> elements are already offset from regular text, <e>it is rarely +necessary to surround user input with double-quotes</e>. For example, don't +refer to a "<c><c></c>" element like I did in this sentence. Avoiding +the use of unnecessary double-quotes makes a document more readable <d/> and +adorable! +</p> + +<p> +As you might have guessed, <c><b></c> is used to <b>boldface</b> some +text. +</p> + +<p> +<c><e></c> is used to apply emphasis to a word or phrase; for example: +I <e>really</e> should use semicolons more often. As you can see, this text is +offset from the regular paragraph type for emphasis. This helps to give your +prose more <e>punch</e>! +</p> + +<p> +The <c><sub></c> and <c><sup></c> elements are used to specify +<sub>subscript</sub> and <sup>superscript</sup>. +</p> + +</body> +</subsection> +<subsection> +<title><uri></title> +<body> + +<p> +The <c><uri></c> tag is used to point to files/locations on the Internet. +It has two forms <d/> the first can be used when you want to have the actual +URI displayed in the body text, such as this link to +<uri>https://www.gentoo.org/</uri>. To create this link, I typed +<c><uri>https://www.gentoo.org/</uri></c>. The alternate form is +when you want to associate a URI with some other text <d/> for example, +<uri link="https://www.gentoo.org/">the Gentoo Linux website</uri>. To create +<e>this</e> link, I typed <c><uri link="https://www.gentoo.org/">the +Gentoo Linux website</uri></c>. +</p> + +<p> +Please avoid the <uri link="https://en.wikipedia.org/wiki/Click_here">click +here syndrome</uri> as recommended by the +<uri link="https://www.w3.org/QA/Tips/noClickHere">W3C</uri>. +</p> + +</body> +</subsection> +<subsection> +<title>Intra-document references</title> +<body> + +<p> +DevBook XML makes it really easy to reference other parts of the document using +hyperlinks. You can create a link pointing to another chapter, like +<uri link="::ebuild-writing/file-format/">Ebuild File Format</uri>, by typing +<c><uri link="::ebuild-writing/file-format/">Ebuild File +Format</uri></c>, i.e., two colons followed by the relative path from +the root node. To refer to a section in another chapter, like +<uri link="::quickstart/#First Ebuild">First Ebuild</uri>, type +<c><uri link="::quickstart/#First Ebuild">First Ebuild</uri></c>. +</p> + +<p> +If the link target's chapter (or section etc.) title is to be used as the link +text, an empty <c><uri></c> element can be used. As a matter of fact, +I could have written the two examples above in more compact form: +<c><uri link="::ebuild-writing/file-format/"/></c> and +<c><uri link="::quickstart/#First Ebuild"/></c> render as +<uri link="::ebuild-writing/file-format/"/> and +<uri link="::quickstart/#First Ebuild"/>, respectively. +</p> + +</body> +</subsection> +</section> + +<section> +<title>Coding Style</title> +<body> + +<p> +Since all Gentoo Documentation is a joint effort and several people will +most likely change existing documentation, a coding style is needed. +A coding style contains two sections. The first one is regarding +internal coding <d/> how the XML-tags are placed. The second one is +regarding the content <d/> how not to confuse the reader. +</p> + +<p> +Both sections are described next. +</p> + +</body> + +<subsection> +<title>Internal Coding Style</title> +<body> + +<p> +<b>Newlines</b> must be placed immediately after <e>every</e> DevBook XML tag +(both opening and closing), except for: +<c><title></c>, +<c><th></c>, <c><ti></c>, <c><li></c>, +<c><dt></c>, <c><dd></c>, +<c><b></c>, <c><c></c>, <c><e></c>, <c><d/></c>, +<c><uri></c>. +</p> + +<p> +<b>Blank lines</b> must be placed immediately after <e>every</e> +<c><body></c> (opening tag only) and before <e>every</e> +<c><section></c>, <c><p></c>, <c><pre></c>, +<c><codesample></c>, <c><figure></c>, <c><table></c>, +<c><ul></c>, <c><ol></c>, <c><dl></c>, <c><note></c>, +<c><important></c> and <c><warning></c> (opening tags only). +An exception to this rule applies to tags that are located within list items +or table cells. +</p> + +<p> +<b>Word-wrapping</b> must be applied at 80 characters except inside +<c><pre></c> and <c><codesample></c>. You may only deviate from +this rule when there is no other choice (for instance when a URL exceeds the +maximum amount of characters). The editor must then wrap whenever the first +whitespace occurs. You should try to keep the <e>rendered</e> content of +<c><pre></c> and <c><codesample></c> elements within 80 columns +to help console users. +</p> + +<p> +<b>Indentation</b> may not be used, except with the XML-constructs of which the +parent XML-tags are <c><tr></c> (from <c><table></c>), +<c><ul></c>, <c><ol></c> and <c><dl></c>. If indentation +is used, it <e>must</e> be two spaces for each indentation. That means +<e>no tabs</e> and <e>not</e> more spaces. Besides, tabs are not allowed in +DevBook XML documents (again, except for <pre> and <codesample>). +</p> + +<p> +In case word-wrapping happens in <c><ti></c>, <c><th></c>, +<c><li></c> or <c><dd></c> constructs, indentation must be used for +the content. +</p> + +<p> +An example for indentation is: +</p> + +<codesample lang="sgml"><!-- Indentation Example --> +<table> +<tr> + <th>Foo</th> + <th>Bar</th> +</tr> +<tr> + <ti>This is an example for indentation</ti> + <ti> + In case text cannot be shown within an 80-character wide line, you + must use indentation if the parent tag allows it + </ti> +</tr> +</table> + +<ul> + <li>First option</li> + <li>Second option</li> +</ul> +</codesample> + +<p> +<b>Opening tags</b> with a single attribute may not be split between lines. +For example, don't put a newline between <c><uri</c> and its <c>link</c> +attribute. Break the line before the <c><uri></c> tag instead. +</p> + +<p> +<b>Attributes</b> may not have spaces in between the attribute, the "=" mark, +and the attribute value. As an example: +</p> + +<codesample lang="sgml"><!-- Attributes --> +Wrong : <uri link = "https://www.gentoo.org/"> +Correct: <uri link="https://www.gentoo.org/"> +</codesample> + +<p> +<b>Dashes</b> used as in-sentence punctuation <d/> like this <d/> should be +written as a <c><d/></c> tag surrounded by spaces. It would be difficult +to distinguish a Unicode em-dash from a hyphen when editing the source using a +fixed-width font. +</p> + +</body> +</subsection> +<subsection> +<title>External Coding Style</title> +<body> + +<p> +Inside tables (<c><table></c>) and listings (<c><ul></c>, +<c><ol></c> and <c><dl></c>), periods (".") should not be used +unless multiple sentences are used. In that case, every sentence should end +with a period (or other reading marks). +</p> + +<p> +Every sentence, including those inside tables and listings, should start +with a capital letter. +</p> + +<codesample lang="sgml"><!-- Periods and capital letters --> +<ul> + <li>No period</li> + <li>With period. Multiple sentences, remember?</li> +</ul> +</codesample> + +<p> +Try to use <c><uri></c> with the <c>link</c> attribute as much as +possible. In other words, the +<uri link="https://www.gentoo.org/">Gentoo website</uri> is preferred over +<uri>https://www.gentoo.org/</uri>. +</p> + +</body> +</subsection> +</section> +</chapter> +</guide> diff --git a/appendices/editor-configuration/emacs/text.xml b/appendices/editor-configuration/emacs/text.xml index 55fade0..9300a69 100644 --- a/appendices/editor-configuration/emacs/text.xml +++ b/appendices/editor-configuration/emacs/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/editor-configuration/emacs/"> <chapter> <title>Configuring GNU Emacs</title> @@ -43,14 +43,14 @@ Files must end with a newline, in order to let tools like <c>diff</c> operate properly. To avoid accidental deletions, setting <c>(setq require-final-newline 'ask)</c> in your startup file will automatically check for the existence of it and ask you to add one. +Note that many modes for programming languages will add the newline +automatically before saving the file. </p> <p> Other useful settings can be disabled backup files -(by <c>(setq make-backup-files nil)</c> and -<c>(setq vc-cvs-stay-local nil)</c>), so you don't clutter CVS -directories and confuse repoman with it (by adding unnecessary entries -into a Manifest file e.g.). Emacs can even contact the outside world +(by <c>(setq make-backup-files nil)</c>), so you don't clutter the git +repository directories. Emacs can even contact the outside world by using the X servers clipboard abilities when yanking, which is activated by <c>(setq x-select-enable-clipboard t)</c>. </p> @@ -69,6 +69,13 @@ It supports ebuilds and eclasses, highlights keywords and also provides a hook for your own customisation. </p> +<p> +Package <c>app-emacs/nxml-gentoo-schemas</c> improves editing of +Gentoo specific XML files (e.g., <c>metadata.xml</c>). It provides +auto-completion and on-the-fly validation, using a RELAX NG schema +for each document type. +</p> + </body> </section> @@ -78,20 +85,20 @@ provides a hook for your own customisation. <ul> <li> - <uri link="http://www.gnu.org/software/emacs/manual/html_node/emacs/Recognize-Coding.html"> - http://www.gnu.org/software/emacs/manual/html_node/emacs/Recognize-Coding.html</uri> + <uri link="https://www.gnu.org/software/emacs/manual/html_node/emacs/Recognize-Coding.html"> + https://www.gnu.org/software/emacs/manual/html_node/emacs/Recognize-Coding.html</uri> </li> <li> - <uri link="http://www.gnu.org/software/emacs/manual/html_node/emacs/Specify-Coding.html"> - http://www.gnu.org/software/emacs/manual/html_node/emacs/Specify-Coding.html</uri> + <uri link="https://www.gnu.org/software/emacs/manual/html_node/emacs/Specify-Coding.html"> + https://www.gnu.org/software/emacs/manual/html_node/emacs/Specify-Coding.html</uri> </li> <li> - <uri link="http://www.emacswiki.org/emacs/UnicodeEncoding"> - http://www.emacswiki.org/emacs/UnicodeEncoding</uri> + <uri link="https://www.emacswiki.org/emacs/UnicodeEncoding"> + https://www.emacswiki.org/emacs/UnicodeEncoding</uri> </li> <li> - <uri link="http://www.emacswiki.org/emacs/ChangingEncodings"> - http://www.emacswiki.org/emacs/ChangingEncodings</uri> + <uri link="https://www.emacswiki.org/emacs/ChangingEncodings"> + https://www.emacswiki.org/emacs/ChangingEncodings</uri> </li> </ul> diff --git a/appendices/editor-configuration/text.xml b/appendices/editor-configuration/text.xml index 071380c..fa1547d 100644 --- a/appendices/editor-configuration/text.xml +++ b/appendices/editor-configuration/text.xml @@ -1,18 +1,14 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/editor-configuration/"> <chapter> <title>Editor Configuration</title> <body> <p> -This section provides hints as to how to configue your text editor for working with ebuilds. +This section provides hints as to how to configure your text editor for working +with ebuilds. </p> -<todo> -from vapier: add a section for nano ... users just have to copy -/etc/nanorc to ~/.nanorc and uncomment the sections for ebuilds -</todo> - </body> <section> diff --git a/appendices/editor-configuration/vim/text.xml b/appendices/editor-configuration/vim/text.xml index e0d34e8..ffcf686 100644 --- a/appendices/editor-configuration/vim/text.xml +++ b/appendices/editor-configuration/vim/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/editor-configuration/vim/"> <chapter> <title>Configuring <c>vim</c> and <c>gvim</c></title> diff --git a/appendices/editor-configuration/xemacs/text.xml b/appendices/editor-configuration/xemacs/text.xml index c1a1ee7..a4105cc 100644 --- a/appendices/editor-configuration/xemacs/text.xml +++ b/appendices/editor-configuration/xemacs/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/editor-configuration/xemacs/"> <chapter> <title>Configuring XEmacs for UTF-8</title> diff --git a/appendices/further-reading/text.xml b/appendices/further-reading/text.xml index 9fa79af..b727322 100644 --- a/appendices/further-reading/text.xml +++ b/appendices/further-reading/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/further-reading/"> <chapter> <title>Further Reading</title> @@ -8,6 +8,7 @@ This section lists some recommended further reading. These are real recommendations, not padding designed to make this document look important. </p> +</body> <section> <title>Books</title> @@ -18,12 +19,12 @@ recommendations, not padding designed to make this document look important. Mastering Regular Expressions </dt> <dd> - <p> - "Mastering Regular Expressions" by Jeffrey E. F. Friedl (O'Reilly, - ISBN 0-596-00289-0) is <b>the</b> book on regular expressions. Very readable and - devoid of the usual mathematical jargon that tends to fill up these kinds of - books. <uri link="http://www.oreilly.com/catalog/regex2/">Publisher's page</uri> - </p> + "Mastering Regular Expressions" by Jeffrey E. F. Friedl (3rd edition, + O'Reilly, 2006, ISBN 0-596-52812-4) is <b>the</b> book on regular + expressions. Very readable and devoid of the usual mathematical jargon + that tends to fill up these kinds of books. + <uri link="https://www.oreilly.com/library/view/mastering-regular-expressions/0596528124/"> + Publisher's page</uri> </dd> </dl> @@ -39,28 +40,22 @@ recommendations, not padding designed to make this document look important. Making Packager-Friendly Software </dt> <dd> - <p> - <uri link="http://www.onlamp.com/pub/a/onlamp/2005/03/31/packaging.html">Making - Packager-Friendly Software</uri> by Julio M. Merino Vidal describes various things - that can be done by upstream software providers to make life easy for the - distribution people (that means you). - </p> + <uri link="https://jmmv.dev/2005/03/making-packager-friendly-software-1.html"> + Making Packager-Friendly Software</uri> by Julio M. Merino Vidal describes + various things that can be done by upstream software providers to make life + easy for the distribution people (that means you). </dd> <dt> How to Report Bugs Effectively </dt> <dd> - <p> - <uri link="http://freshmeat.net/articles/view/149">How to Report Bugs + <uri link="https://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report Bugs Effectively</uri> by Simon Tatham is a good overview of effective bug reporting. - </p> </dd> </dl> </body> </section> - -</body> </chapter> </guide> diff --git a/appendices/text.xml b/appendices/text.xml index dc326a6..effc5b5 100644 --- a/appendices/text.xml +++ b/appendices/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/"> <chapter> <title>Appendices</title> @@ -21,6 +21,7 @@ This section incorporates various auxiliary documents which may be useful as a r <include href="common-problems/"/> <include href="further-reading/"/> <include href="contributing/"/> +<include href="devbook-guide/"/> <include href="contributors/"/> <include href="todo-list/"/> diff --git a/appendices/todo-list/text.xml b/appendices/todo-list/text.xml index e8175c5..a1464f2 100644 --- a/appendices/todo-list/text.xml +++ b/appendices/todo-list/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/todo-list/"> <chapter> <title>TODO List</title> diff --git a/archs/alpha/text.xml b/archs/alpha/text.xml index b8662fe..32b539b 100644 --- a/archs/alpha/text.xml +++ b/archs/alpha/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="archs/alpha/"> <chapter> -<title>Arch Specific Notes -- Alpha</title> +<title>Arch Specific Notes — Alpha</title> <body> <p> @@ -9,6 +9,7 @@ The Alpha port uses the <c>alpha</c> keyword. It focuses upon HP (formerly Compa (formerly DEC)) hardware. This covers from <c>ev4</c> (known as 21064) through <c>ev7z</c> (known as 21364a). </p> +</body> <section> <title>Alpha Kernel and Userland ABIs</title> @@ -86,7 +87,7 @@ which the compiler was built. <p> The <c>-mieee</c> flag <b>should</b> always be used unless you have a deep knowledge of the Alpha architecture, so the comments on -<uri link="::general-concepts/user-environment#Not Filtering Variables"/> are +<uri link="::general-concepts/user-environment/#Not Filtering Variables"/> are really important on Alpha. </p> @@ -125,7 +126,7 @@ The Alpha team can be contacted: Via email to the <c>gentoo-alpha</c> mailing list </li> <li> - Via the <c>#gentoo-alpha</c> IRC channel on Freenode + Via the <c>#gentoo-alpha</c> IRC channel on Libera.Chat </li> </ul> @@ -138,22 +139,20 @@ The Alpha team can be contacted: <ul> <li> - <uri link="http://alpha.gentoo.org/">Gentoo Linux Alpha Development Project</uri> + <uri link="https://wiki.gentoo.org/wiki/Project:Alpha">Gentoo Linux Alpha Development Project</uri> </li> <li> - <uri link="http://www.gentoo.org/doc/en/gentoo-alpha-faq.xml">Gentoo/Alpha FAQ</uri> + <uri link="https://wiki.gentoo.org/wiki/Alpha/FAQ">Gentoo/Alpha FAQ</uri> </li> <li> - <uri link="http://www.gentoo.org/proj/en/base/alpha/doc/alpha-porting-guide.xml">Alpha Porting Guide</uri> + <uri link="https://wiki.gentoo.org/wiki/Project:Alpha/Porting_guide">Alpha Porting Guide</uri> </li> <li> - <uri link="http://forums.gentoo.org/viewforum-f-32.html">Gentoo on Alternative Architectures Forum</uri> + <uri link="https://forums.gentoo.org/viewforum-f-32.html">Gentoo on Alternative Architectures Forum</uri> </li> </ul> </body> </section> - -</body> </chapter> </guide> diff --git a/archs/amd64/text.xml b/archs/amd64/text.xml index 3019b4b..f227005 100644 --- a/archs/amd64/text.xml +++ b/archs/amd64/text.xml @@ -1,8 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="archs/amd64/"> <chapter> -<title>Arch Specific Notes -- AMD64/EM64T</title> -<body> +<title>Arch Specific Notes — AMD64/EM64T</title> <section> <title>Position Independent Code Issues</title> @@ -20,6 +19,7 @@ with an error message like this: foo.o: relocation R_X86_64_32 can not be used when making a shared object; recompile with -fPIC </pre> +</body> <subsection> <title>How to fix -fPIC issues</title> @@ -29,6 +29,7 @@ object; recompile with -fPIC There are several ways to enforce <c>-fPIC</c> on shared objects, each with its pros and cons. </p> +</body> <subsubsection> <title><c>sed</c>'ing the Makefile</title> @@ -54,8 +55,6 @@ This is more readable, and easier to send upstream. </body> </subsubsection> - -</body> </subsection> <subsection> @@ -70,59 +69,13 @@ doesn't help upstream at all. <p> Another bad idea is to (ab)use <c>append-flags</c> function from -<c>flag-o-matic.eclass</c>. Applying <c>-fPIC</c> on all objects should not be -done. It should only be applied to shared objects. +<c><uri link="::eclass-reference/flag-o-matic.eclass/"/></c>. +Applying <c>-fPIC</c> on all objects should not be done. It should only be +applied to shared objects. </p> </body> </subsection> - -</body> -</section> - -<section> -<title>Assembler Optimisation</title> -<body> - -<p> -Modern x86 processors support special instruction sets like <c>mmx</c>, <c>sse</c>, -<c>SSE2</c> and <c>3DNow!</c>. AMD64 also provides support for them, but in most -cases, x86 assembler code is incompatible with AMD64 assembler. There are lots -of packages that provide support through USE flags for these instruction sets. -Originally, the USE flags were introduced to keep support for older processors -such as the Pentium I that can't handle such code. Currently, all AMD64s support the -same combination of extended instruction sets, so there is no reason to make -use of the mentioned USE flags. That's why these USE flags are hard-masked in -all AMD64-profiles. This doesn't mean we don't support the extensions -themselves, instead, we hard-enable them. -</p> - -<p> -The following USE flags are masked on AMD64: -</p> - -<ul> - <li> - mmx - </li> - <li> - mmx2 - </li> - <li> - sse - </li> - <li> - sse2 - </li> - <li> - 3dnow - </li> - <li> - 3dnowext - </li> -</ul> - -</body> </section> <section> @@ -138,10 +91,10 @@ go to <c>/lib32</c> respectively <c>/usr/lib32</c>, the 64bit ones normally to < <c>/usr/lib64</c>. In a perfect world, you wouldn't have to read on. Unfortunately, that's not the case, and so it's a bit more complicated. </p> +</body> <subsection> <title>Multilib-Toolchain</title> -<body> <subsubsection> <title>GCC</title> @@ -174,177 +127,82 @@ To understand how this is done in the ebuild, read </body> </subsubsection> - -</body> </subsection> <subsection> -<title>The <c>emul-linux-x86-*</c> packages</title> +<title>32bit compatibility</title> <body> <p> As you read above, 32bit applications must be linked against 32bit libraries. -For that, we've put together the most used libraries and stuck them into the -so-called <c>emul-linux-x86</c> packages, which are located in the -<c>app-emulation</c> category. The current list of all the <c>emul-linux-x86</c> -packages, can be found <uri link="http://dev.gentoo.org/~pacho/emul.html">here.</uri> +For that, we've made the most common libraries as multilib (via <c>ABI</c> +variable and <c><uri link="::eclass-reference/multilib.eclass/"/></c>). </p> -<p> -These packages only provide pre-compiled libraries. Currently, the -archives are assembled manually, which is the main reason to keep the packages -as tidy as possible. Do not include libraries that aren't commonly used. -</p> - -<note> - The emul-packages might conflict with their native images, but only in - uncritical locations like <c>/usr/share</c> which are arch-independent anyway. -</note> - </body> </subsection> <subsection> -<title><c>Libdir</c> Links</title> +<title>Libdir links</title> <body> <p> -Currently, we provide several profiles, each with its own combination of <c>libdir</c> -configurations. +Currently, we provide several profiles, each with its own combination of +<c>libdir</c> configurations. Table entries x86, amd64, etc. indicate that +the directory contains objects for this ABI; entries with an arrow indicate +a symlink to the respective directory. </p> <table> <tr> - <th> - Profile - </th> - <th> - lib32 - </th> - <th> - lib - </th> - <th> - lib64 - </th> + <th>Profile</th> + <th>lib</th> + <th>lib32</th> + <th>lib64</th> + <th>libx32</th> </tr> <tr> - <ti> - 2004.3 - </ti> - <ti> - *l->emul* - </ti> - <ti> - d64 - </ti> - <ti> - *l->lib* - </ti> + <ti>17.0</ti> + <ti>-> lib64</ti> + <ti>x86</ti> + <ti>amd64</ti> + <ti>non-existent</ti> </tr> <tr> - <ti> - 2004.3/lib64 - </ti> - <ti> - *l->emul* - </ti> - <ti> - *l->64* - </ti> - <ti> - d64 - </ti> + <ti>17.0/no-multilib</ti> + <ti>-> lib64</ti> + <ti>non-existent</ti> + <ti>amd64</ti> + <ti>non-existent</ti> </tr> <tr> - <ti> - >=2005.0 - </ti> - <ti> - d32 - </ti> - <ti> - *l->64* - </ti> - <ti> - d64 - </ti> + <ti>17.0/x32</ti> + <ti>-> libx32</ti> + <ti>x86</ti> + <ti>amd64</ti> + <ti>x32</ti> </tr> <tr> - <ti> - >=2005.0/no-multilib - </ti> - <ti> - d32 - </ti> - <ti> - *l->64* - </ti> - <ti> - d64 - </ti> - </tr> - <tr> - <ti> - >=2005.0/no-symlink - </ti> - <ti> - d32 - </ti> - <ti> - d - </ti> - <ti> - d64 - </ti> + <ti>17.1</ti> + <ti>x86</ti> + <ti>non-existent</ti> + <ti>amd64</ti> + <ti>non-existent</ti> </tr> <tr> - <ti> - >=2005.0/no-symlink/no-lib32 - </ti> - <ti> - inexistant - </ti> - <ti> - d32 - </ti> - <ti> - d64 - </ti> + <ti>17.1/no-multilib</ti> + <ti>n/a</ti> + <ti>non-existent</ti> + <ti>amd64</ti> + <ti>non-existent</ti> </tr> </table> -<dl> - <dt> - d - </dt> - <dd> - <p> - Directory containing mixed-bit objects - </p> - </dd> - <dt> - dXX - </dt> - <dd> - <p> - Directory containing XXbit objects - </p> - </dd> - <dt> - l->foo - </dt> - <dd> - <p> - Link to foo - </p> - </dd> -</dl> - <p> -To always get the right path, you should use the function <c>$(get_libdir)</c> from -<c>multilib.eclass</c>. It will always return the correct directory, on all arches. -And of course it also takes care of the <c>ABI</c> variable. +To always get the right path, you should use <c>$(get_libdir)</c> which is +available as a package manager function since EAPI 6. It will always return +the correct directory, on all arches. And of course it also takes care of +the <c>ABI</c> variable. </p> </body> @@ -357,7 +215,7 @@ And of course it also takes care of the <c>ABI</c> variable. <p> Many Makefiles assume that their libraries should go to <c>/usr/lib</c>, or <c>$(prefix)/lib</c>. This assumption can cause a serious mess if <c>/usr/lib</c> -isn't a symlink to <c>/usr/lib64</c>. To find the bad packages, we have a portage feature +isn't a symlink to <c>/usr/lib64</c>. To find the bad packages, we have a Portage feature called <b>multilib-strict</b>. It will prevent emerge from putting 64bit libraries into anything other than <c>(/usr)/lib64</c>. </p> @@ -367,31 +225,17 @@ into anything other than <c>(/usr)/lib64</c>. this behaviour is controlled by the <c>MULTILIB_STRICT_EXEMPT</c> variable in <c>make.profile</c>. </p> +</body> <subsubsection> <title>How to fix ebuilds properly</title> <body> <p> -In most cases, it's sufficient to use the <c>$(get_libdir)</c> function from -<c>multilib.eclass</c>: +In most cases, default <c>econf</c> behaviour is sufficient, because it will +pass the correct <c>--libdir</c> option to <c>configure</c>. </p> -<codesample lang="ebuild"> -inherit multilib - -src_compile() { - econf \ - --libdir=/usr/$(get_libdir) - - emake || die -} - -src_install() { - emake DESTDIR="${D}" install || die -} -</codesample> - <p> Some packages provide really bad Makefiles which hard-code <c>/usr/lib</c>. Those should be <c>sed</c> -ed or patched. Don't forget to let upstream know about your @@ -400,8 +244,6 @@ modifications! </body> </subsubsection> - -</body> </subsection> <subsection> @@ -435,7 +277,7 @@ As you can see, this is just a wrapper that decides which file you need depending on the parameter <c>-D</c> given to gcc. You'll probably run into some troubles if you try to compile something by hand and forget to append <c>-D__x86_64__</c> to your <c>CFLAGS</c>. Of course, this is <b>not necessary</b> when -using portage. For an explanation, see the <uri link="::archs/amd64/#The ABI Variable"/> +using Portage. For an explanation, see the <uri link="::archs/amd64/#The ABI Variable"/> section. </p> @@ -447,7 +289,7 @@ section. <body> <p> -Whenever portage builds something on amd64, it has to decide whether it should +Whenever Portage builds something on amd64, it has to decide whether it should be 32bit or 64bit. As stated in <uri link="::archs/amd64/#Headers and Multilib"/> the <c>__i386__</c> or <c>__x86_64__</c> respectively, is needed in <c>CDEFINE</c>. Also, gcc has to know what code it should produce, therefore <c>-m32</c> or <c>-m64</c> @@ -478,13 +320,10 @@ LIBDIR_x86="lib32" </body> </subsection> - -</body> </section> <section> <title>Porting Notes</title> -<body> <subsection> <title>Machine Word sizes</title> @@ -631,8 +470,6 @@ segmentation faults or strange behaviour. GCC 4.0 refuses to compile such code. </body> </subsection> - -</body> </section> <section> @@ -641,19 +478,17 @@ segmentation faults or strange behaviour. GCC 4.0 refuses to compile such code. <ul> <li> - <uri link="http://amd64.gentoo.org/">Gentoo/AMD64 Project</uri> + <uri link="https://wiki.gentoo.org/wiki/Project:AMD64">Gentoo/AMD64 Project</uri> </li> <li> - <uri link="http://www.gentoo.org/doc/en/gentoo-amd64-faq.xml">Gentoo/Linux AMD64 FAQ</uri> + <uri link="https://wiki.gentoo.org/wiki/AMD64/FAQ">Gentoo/Linux AMD64 FAQ</uri> </li> <li> - <uri link="http://forums.gentoo.org/viewforum-f-46.html">Gentoo on AMD64 Forum</uri> + <uri link="https://forums.gentoo.org/viewforum-f-46.html">Gentoo on AMD64 Forum</uri> </li> </ul> </body> </section> - -</body> </chapter> </guide> diff --git a/archs/mips/text.xml b/archs/mips/text.xml index 776c15c..436e361 100644 --- a/archs/mips/text.xml +++ b/archs/mips/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="archs/mips/"> <chapter> -<title>Arch Specific Notes -- MIPS</title> +<title>Arch Specific Notes — MIPS</title> <body> <p> @@ -23,6 +23,7 @@ calling functions) and the size of data types. ISA stands for "Instruction Set Architecture", and refers to the instructions available and the number and types of registers for a given CPU. </note> +</body> <section> <title>MIPS ABIs</title> @@ -127,13 +128,11 @@ The MIPS team can be contacted: Via email to the <c>gentoo-mips</c> mailing list </li> <li> - Via the <c>#gentoo-mips</c> IRC channel on Freenode + Via the <c>#gentoo-mips</c> IRC channel on Libera.Chat </li> </ul> </body> </section> - -</body> </chapter> </guide> diff --git a/archs/ppc/text.xml b/archs/ppc/text.xml index 6313f81..e6a4966 100644 --- a/archs/ppc/text.xml +++ b/archs/ppc/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="archs/ppc/"> <chapter> -<title>Arch Specific Notes -- PPC</title> +<title>Arch Specific Notes — PPC</title> <body> <p> @@ -9,6 +9,7 @@ The Gentoo PowerPC port uses the <c>ppc</c> keyword and maintains compatibility all 32 bit PowerPC processors. It is also used for 32 bit userland installs on 64 bit PowerPC systems. </p> +</body> <section> <title>Common issues</title> @@ -70,7 +71,7 @@ The PowerPC team can be reached by: <ul> <li> - Via the <c>#gentoo-ppc</c> IRC channel on freenode + Via the <c>#gentoo-powerpc</c> IRC channel on Libera.Chat </li> <li> Via email to <c>ppc@gentoo.org</c> @@ -92,16 +93,14 @@ The PowerPC team can be reached by: <ul> <li> - <uri link="http://www.gentoo.org/doc/en/gentoo-ppc-faq.xml">Gentoo PPC FAQ</uri> + <uri link="https://wiki.gentoo.org/wiki/PPC/FAQ">Gentoo PPC FAQ</uri> </li> <li> - <uri link="http://forums.gentoo.org/viewforum-f-24.html">Gentoo PPC Forums</uri> + <uri link="https://forums.gentoo.org/viewforum-f-24.html">Gentoo PPC Forums</uri> </li> </ul> </body> </section> - -</body> </chapter> </guide> diff --git a/archs/sparc/text.xml b/archs/sparc/text.xml index f514c86..5cfbdf2 100644 --- a/archs/sparc/text.xml +++ b/archs/sparc/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="archs/sparc/"> <chapter> -<title>Arch Specific Notes -- SPARC</title> +<title>Arch Specific Notes — SPARC</title> <body> <p> @@ -11,6 +11,21 @@ and 2.4 kernels should still work with Gentoo, but they are no longer supported by the Gentoo/SPARC team. </p> +<p> +SPARC systems are notoriously strict on aligned access: this is the most common +type of bug seen on SPARC (other than big-endian related issues), causing a +<c>SIGBUS</c> signal to be sent to the errant process. Known issues should be +linked to +<uri link="https://bugs.gentoo.org/371525">the related tracker bug</uri>. +</p> + +<p> +This is usually due to supposedly clever pointer casts and type punning tricks +by the code authors. +</p> + +</body> + <section> <title>SPARC Kernel and Userland ABIs</title> <body> @@ -40,8 +55,8 @@ buses. <note> This section is in addition to the guidelines in -<uri link="::keywording#Keywording on Upgrades"/>. It discusses <e>additional</e> -requirements for the SPARC architecture. +<uri link="::keywording/#Keywording on Upgrades"/>. It discusses +<e>additional</e> requirements for the SPARC architecture. </note> <p> @@ -101,7 +116,7 @@ code. Depending upon the application, this can be anywhere up to five times slower than <c>v9</c> code when running on an UltraSparc <d/> cryptographic and graphics applications which make heavy use of integer multiplication and division are especially badly hit. For this reason, the comments in -<uri link="::general-concepts/user-environment#Not Filtering Variables"/> +<uri link="::general-concepts/user-environment/#Not Filtering Variables"/> are especially important on SPARC. </p> @@ -127,14 +142,12 @@ The SPARC team can be contacted: Via email to the <c>gentoo-sparc</c> mailing list </li> <li> - Via the <c>#gentoo-sparc</c> IRC channel on Freenode + Via the <c>#gentoo-sparc</c> IRC channel on Libera.Chat </li> </ul> </body> </section> - -</body> </chapter> </guide> diff --git a/archs/text.xml b/archs/text.xml index 4eb9750..137920b 100644 --- a/archs/text.xml +++ b/archs/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="archs/"> <chapter> <title>Arch Specific Notes</title> diff --git a/archs/x86/text.xml b/archs/x86/text.xml index e0b7894..76f57c2 100644 --- a/archs/x86/text.xml +++ b/archs/x86/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="archs/x86/"> <chapter> -<title>Arch Specific Notes -- x86</title> +<title>Arch Specific Notes — x86</title> <body> <p> @@ -17,6 +17,7 @@ contact the x86 team. If your package requires specific hardware, or a specific non-trivial setup to test, then we will probably allow you to mark it stable, unless someone on the team can test it. </p> +</body> <section> <title>x86 Team Guidelines</title> @@ -31,7 +32,7 @@ The following is a list of rules and expectations for members of the x86 team: Assist/resolve 4 bugs a month that are assigned to the team </li> <li> - Be present in our IRC channel, <c>#gentoo-x86/irc.freenode.net</c> + Be present in our IRC channel, <c>#gentoo-x86/irc.libera.chat</c> </li> <li> If you need one of your packages stable, file a bug to the team. You are not @@ -61,13 +62,11 @@ The x86 team can be contacted: Via email to the <c>x86@</c> email alias </li> <li> - Via the <c>#gentoo-x86</c> IRC channel on Freenode + Via the <c>#gentoo-x86</c> IRC channel on Libera.Chat </li> </ul> </body> </section> - -</body> </chapter> </guide> diff --git a/bin/build_search_documents.py b/bin/build_search_documents.py new file mode 100755 index 0000000..6782969 --- /dev/null +++ b/bin/build_search_documents.py @@ -0,0 +1,124 @@ +#!/usr/bin/python3 +# Copyright 2019 Gentoo Authors +# Distributed under the terms of the GNU GPL version 2 or later +import json +import os.path +import sys +import xml.etree.ElementTree as ET +import re + + +# The regex for stripping a newline and the possible indentation +# whitespace following it in multiline content +whitespace_re = re.compile(r'\n[ \t]*', flags=re.M) + + +def stringify_node(parent: ET.Element) -> str: + """Flatten this node and its immediate children to a string. + + Combine the text and tail of this node, and any of its immediate + children, if there are any, into a flat string. The tag <d/> is a + special case that resolves to the dash ('-') character. + + Keyword arguments: + parent -- the node to convert to a string + + """ + # We usually have something like: + # <p>\nText + # Left strip the whitespace. + if parent.text: + text = parent.text.lstrip() + else: + text = str() + + # For each child, strip the tags and append to text + # along with the tail text following it. + # The tail may include '\n', '\t', ' ' if it spans multiple lines. + # We will worry about those on return, not now. + for child in parent: + # The '<d/>' tag is simply a fancier '-' character + if child.tag == 'd': + text += '-' + if child.text: + text += child.text + if child.tail: + text += child.tail + + # A paragraph typically ends with: + # Text\n</p> + # Right strip any spurious whitespace. + # Finally, get rid of any intermediate newlines and indentation whitespace. + return whitespace_re.sub(' ', text.rstrip()) + + +def process_node(documents: list, node: ET.Element, name: str, url: str) -> None: + """Recursively process a given node and its children based on tag values. + + For the top level node <chapter>, extract the title and recurse + down to the children. + For the intermediary nodes with titles, such as <section>, update + the search result title and url, and recurse down. + For the terminal nodes, such as <p>, convert the contents of the + node to a string, and add it to the search documents. + + Keyword arguments: + documents -- the search documents array + node -- the node to process + name -- the title to display for the search term match + url -- the url for the search term match in the document + + """ + if node.tag == 'chapter': + name = stringify_node(node.find('title')) + + for child in node: + process_node(documents, child, name, url) + elif node.tag in ['section', 'subsection', 'subsubsection']: + title = stringify_node(node.find('title')) + name += ' -> ' + title + url = "{url_base}#{anchor}".format( + url_base=url.split('#')[0], + anchor=title.lower().replace(' ', '-')) + + for child in node: + process_node(documents, child, name, url) + elif node.tag in ['body', 'dl', 'guide', 'ul', 'table', 'tr']: + for child in node: + process_node(documents, child, name, url) + elif node.tag in ['p', 'dd', 'dt', 'important', 'li', 'note', 'warning', 'th', 'ti']: + text = stringify_node(node) + + documents.append({'id': len(documents), + 'name': name, + 'text': text, + 'url': url}) + else: + pass + + +def main(pathnames: list) -> None: + """The entry point of the script. + + Keyword arguments: + pathnames -- a list of path names to process in sequential order + """ + url_root = 'https://devmanual.gentoo.org/' + documents = [] + + for path in pathnames: + tree = ET.parse(path) + root = tree.getroot() + + try: + url = url_root + os.path.dirname(path) + '/' + + process_node(documents, root, None, url) + except: + raise + + print('var documents = ' + json.dumps(documents) + ';') + + +if __name__ in '__main__': + main(sys.argv[1:]) diff --git a/bin/gen-eclass-html.sh b/bin/gen-eclass-html.sh new file mode 100755 index 0000000..2d40cb6 --- /dev/null +++ b/bin/gen-eclass-html.sh @@ -0,0 +1,210 @@ +#!/bin/bash + +# pre1) OOB: The host needs to emerge eclass-manpages on a daily basis. +# This script should be run before the make operation is performed + +set -o pipefail + +OUTPUTDIR="eclass-reference" + +IFS='' read -r -d '' HEADER << 'EOF' +<!DOCTYPE html> +<html lang="en"> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <title>@TITLE@ – Gentoo Development Guide</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <meta name="description" content="The Gentoo Devmanual is a technical manual which covers topics such as writing ebuilds and eclasses, and policies that developers should be abiding by."> + <link href="https://assets.gentoo.org/tyrian/bootstrap.min.css" rel="stylesheet" media="screen"> + <link href="https://assets.gentoo.org/tyrian/tyrian.min.css" rel="stylesheet" media="screen"> + <link rel="stylesheet" href="../../devmanual.css" type="text/css"> + <link rel="icon" href="https://www.gentoo.org/favicon.ico" type="image/x-icon"> +</head> +<body> +<header><div class="site-title"><div class="container"><div class="row"> +<div class="site-title-buttons"><div class="btn-group btn-group-sm"> +<a href="https://get.gentoo.org/" role="button" class="btn get-gentoo"><span class="fa fa-fw fa-download"></span><strong> Get Gentoo!</strong></a><div class="btn-group btn-group-sm"> +<a class="btn gentoo-org-sites dropdown-toggle" data-toggle="dropdown" data-target="#" href="#"><span class="fa fa-fw fa-map-o"></span><span class="hidden-xs"> gentoo.org sites </span><span class="caret"></span></a><ul class="dropdown-menu dropdown-menu-right"> +<li><a href="https://www.gentoo.org/" title="Main Gentoo website"><span class="fa fa-home fa-fw"></span> gentoo.org</a></li> +<li><a href="https://wiki.gentoo.org/" title="Find and contribute documentation"><span class="fa fa-file-text-o fa-fw"></span> Wiki</a></li> +<li><a href="https://bugs.gentoo.org/" title="Report issues and find common issues"><span class="fa fa-bug fa-fw"></span> Bugs</a></li> +<li><a href="https://forums.gentoo.org/" title="Discuss with the community"><span class="fa fa-comments-o fa-fw"></span> Forums</a></li> +<li><a href="https://packages.gentoo.org/" title="Find software for your Gentoo"><span class="fa fa-hdd-o fa-fw"></span> Packages</a></li> +<li class="divider"></li> +<li><a href="https://planet.gentoo.org/" title="Find out what's going on in the developer community"><span class="fa fa-rss fa-fw"></span> Planet</a></li> +<li><a href="https://archives.gentoo.org/" title="Read up on past discussions"><span class="fa fa-archive fa-fw"></span> Archives</a></li> +<li><a href="https://sources.gentoo.org/" title="Browse our source code"><span class="fa fa-code fa-fw"></span> Sources</a></li> +<li class="divider"></li> +<li><a href="https://infra-status.gentoo.org/" title="Get updates on the services provided by Gentoo"><span class="fa fa-server fa-fw"></span> Infra Status</a></li> +</ul> +</div> +</div></div> +<div> +<a href="/" title="Back to the homepage" class="site-logo"><object data="https://assets.gentoo.org/tyrian/site-logo.svg" type="image/svg+xml"><img src="https://assets.gentoo.org/tyrian/site-logo.png" alt="Gentoo Linux Logo"></object></a><span class="site-label">Development Guide</span> +</div> +</div></div></div> +<nav class="tyrian-navbar" role="navigation"><div class="container"><div class="row"> +<div class="navbar-header"><button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-main-collapse"><span class="sr-only">Toggle navigation</span><span class="icon-bar"></span><span class="icon-bar"></span><span class="icon-bar"></span></button></div> +<div class="collapse navbar-collapse navbar-main-collapse"><ul class="nav navbar-nav"> +<li><a href="../../index.html"><span class="fa fa-home"></span> Home</a></li> +</ul></div> +</div></div></nav> +<div class="container"><div class="row"><div class="col-md010"> +<ol class="breadcrumb"> +<li><a href="../../index.html">Master Index</a></li> +<li><a href="../index.html">Eclass Reference</a></li> +</ol> +</div></div></div> +</header> +<main><div class="container"> +EOF + +IFS='' read -r -d '' FOOTER << 'EOF' +</div></main> +<footer><div class="container"> +<div class="row"> +<div class="col-xs-12 col-md-offset-2 col-md-7"></div> +<div class="col-xs-12 col-md-3"> +<h3 class="footerhead">Questions or comments?</h3> + Please feel free to <a href="https://www.gentoo.org/inside-gentoo/contact/">contact us</a>. + </div> +</div> +<div class="row"> +<div class="col-xs-2 col-sm-3 col-md-2"> +<ul class="footerlinks three-icons"> +<li><a href="https://twitter.com/gentoo" title="@Gentoo on Twitter"><span class="fa fa-twitter fa-fw"></span></a></li> +<li><a href="https://www.facebook.com/gentoo.org" title="Gentoo on Facebook"><span class="fa fa-facebook fa-fw"></span></a></li> +</ul> +<div class="text-center"> +<a href="https://wiki.gentoo.org/wiki/Foundation:Privacy_Policy">Privacy Policy</a> +</div> +</div> +<div class="col-xs-10 col-sm-9 col-md-10"> +<strong>Copyright (C) 2001-2024 Gentoo Authors</strong><br><small> + Gentoo is a trademark of the Gentoo Foundation, Inc. + The text of this document is distributed under the + <a href="https://www.gnu.org/licenses/gpl-2.0.html">GNU General Public License, version 2</a>. + The <a href="https://www.gentoo.org/inside-gentoo/foundation/name-logo-guidelines.html">Gentoo Name and Logo Usage Guidelines</a> apply. + </small> +</div> +</div> +</div></footer><script src="https://assets.gentoo.org/tyrian/jquery.min.js"></script><script src="https://assets.gentoo.org/tyrian/bootstrap.min.js"></script> +</body> +</html> +EOF + +guesscompress() { + case "$1" in + *.gz|*.z) echo "gunzip -c" ;; + *.bz2|*.bz) echo "bunzip2 -c" ;; + *.lz) echo "lzip -dc" ;; + *.lzma) echo "unlzma -c" ;; + *.lzo) echo "lzop -dc" ;; + *.xz) echo "xzdec" ;; + *.zst) echo "zstd -dc" ;; + *) echo "cat" ;; + esac +} + +usage() { + cat <<- EOF >&2 + Usage: $0 [OPTION]... + Convert eclass man pages to HTML. + + -n do not build anything, only create a placeholder index + -h display this help and exit + EOF +} + +while getopts 'nh' opt; do + case ${opt} in + n) NOMAN=true ;; + h) usage; exit 0 ;; + *) usage; exit 1 ;; + esac +done +shift $((OPTIND-1)) + +MANPAGES=() +[[ -n ${NOMAN} ]] || MANPAGES=( + $(/usr/bin/qlist -e eclass-manpages) + # We also need a couple of Portage man pages + /usr/share/man/man5/ebuild.5* + /usr/share/man/man5/make.conf.5* +) || exit 1 + +[[ -d ${OUTPUTDIR} ]] || mkdir -p "${OUTPUTDIR}" || exit 1 + +for i in "${MANPAGES[@]}"; do + FILEBASE=${i##*/} + BASENAME="${FILEBASE%.5*}" + [[ ${BASENAME} != "${FILEBASE}" ]] || continue + DIRNAME="${OUTPUTDIR}/${BASENAME}" + FINAL="${DIRNAME}/index.html" + DECOMPRESS=$(guesscompress "${i}") + [[ -d ${DIRNAME} ]] || mkdir -p "${DIRNAME}" || exit 1 + # update the dir's mtime to prevent its removal below + touch "${DIRNAME}" || exit 1 + # rebuild the man page each time + echo -n "${HEADER//@TITLE@/${BASENAME}}" > "${FINAL}" || exit 1 + # generate html pages and fix hyperlinks for eclass and other man pages + ${DECOMPRESS} "${i}" | /usr/bin/man2html -r \ + | sed -e '1,/<BODY>/d;/<\/BODY>/,$d' \ + -e '/<A HREF=/s:"\.\./man5/\([^"]*eclass\|ebuild\|make\.conf\)\.5\.html":"../\1/index.html":g' \ + -e 's:<A HREF="\.\./man[^"]*">\([^<>]*\)</A>:\1:g' \ + -e 's:<A HREF="[^"]*//localhost/[^"]*">\([^<>]*\)</A>:\1:g' \ + -e 's:<A HREF="[^"]*\${[^"]*">\([^<>]*\)</A>:\1:g' \ + -e 's,<A HREF="mailto:[^"]*">\([^<>]*\)</A>,\1,g' \ + -e 's:<TT>\([^<>]*\)</TT>:\1:g' \ + -e 's:<DL COMPACT>:<DL>:g' \ + -e 's:<TR VALIGN=top>:<TR>:g' \ + -e '/<A NAME/{N;s:<A NAME=\(.*\)>.*</A>\(.*<H[1-6]\)>:\2 ID=\1>:}' \ + >> "${FINAL}" || exit 1 + echo -n "${FOOTER}" >> "${FINAL}" || exit 1 +done + +# Remove old dirs (eclasses that were dropped from the tree) +find "${OUTPUTDIR}" -mindepth 1 -maxdepth 1 -mtime +1 -exec rm -R {} \; + +# build the index, rebuilding it each time +cat << 'EOF' > "${OUTPUTDIR}"/text.xml || exit 1 +<?xml version="1.0" encoding="UTF-8"?> +<guide self="eclass-reference/"> +<chapter> +<title>Eclass Reference</title> +<body> + +<p> +This section provides a reference for some of the more commonly used eclasses. +Note that most eclasses have an accompanying manual page. These man pages can be +installed by emerging <c>app-doc/eclass-manpages</c>. +</p> + +</body> + +<section> +<title>Contents</title> +<body> +EOF + +if [[ -n ${NOMAN} ]]; then + cat <<- 'EOF' >> "${OUTPUTDIR}"/text.xml || exit 1 + <warning> + This is only a placeholder. If you see this text in the output document, + then the eclass documentation is missing. + </warning> + EOF +else + echo '<ul class="list-group">' >> "${OUTPUTDIR}"/text.xml || exit 1 + for i in $(find "${OUTPUTDIR}" -maxdepth 1 -mindepth 1 -type d | sort); do + echo "<li><uri link=\"$(basename $i)/index.html\">$(basename $i)</uri></li>" >> "${OUTPUTDIR}"/text.xml || exit 1 + done + echo '</ul>' >> "${OUTPUTDIR}"/text.xml || exit 1 +fi + +cat << 'EOF' >> "${OUTPUTDIR}"/text.xml || exit 1 +</body> +</section> +</chapter> +</guide> +EOF diff --git a/depend.xsl b/depend.xsl new file mode 100644 index 0000000..15c5e15 --- /dev/null +++ b/depend.xsl @@ -0,0 +1,45 @@ +<?xml version="1.0" encoding="UTF-8"?> +<xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform' + xmlns:str="http://exslt.org/strings" + xmlns:exslt="http://exslt.org/common" + extension-element-prefixes="str exslt xsl" + exclude-result-prefixes="str exslt xsl"> + +<xsl:import href="devbook.xsl"/> +<xsl:output method="text"/> + +<xsl:template match="/"> + <xsl:variable name="refs"> + <!-- all descendants --> + <xsl:call-template name="contentsTree"/> + <!-- all ancestors --> + <xsl:call-template name="printParentDocs"/> + <!-- previous and next documents --> + <xsl:call-template name="findPrevious"/> + <xsl:call-template name="findNext"/> + </xsl:variable> + <xsl:variable name="self" select="/guide/@self"/> + <xsl:value-of select="concat($self, 'index.html:')"/> + <xsl:for-each select="exslt:node-set($refs)//a/@href[. != '#']"> + <xsl:text> </xsl:text> + <xsl:variable name="path" select="substring-before(., 'index.html')"/> + <!-- At this point, $path can start with zero or more ".." components + and is relative to $self. Convert it to an absolute path. --> + <xsl:variable name="up" select="count(str:tokenize($path, '/')[. = '..'])"/> + <xsl:for-each select="str:tokenize($self, '/')[position() <= last() - $up]"> + <xsl:value-of select="concat(., '/')"/> + </xsl:for-each> + <xsl:for-each select="str:tokenize($path, '/')[position() > $up]"> + <xsl:value-of select="concat(., '/')"/> + </xsl:for-each> + <xsl:text>text.xml</xsl:text> + </xsl:for-each> + <xsl:value-of select="$newline"/> +</xsl:template> + +</xsl:stylesheet> + +<!-- Local Variables: --> +<!-- indent-tabs-mode: nil --> +<!-- fill-column: 120 --> +<!-- End: --> diff --git a/devbook.rnc b/devbook.rnc new file mode 100644 index 0000000..22f7c09 --- /dev/null +++ b/devbook.rnc @@ -0,0 +1,123 @@ +# Copyright 2022-2024 Gentoo Authors +# Distributed under the terms of the MIT license +# or the CC-BY-SA-4.0 license (dual-licensed) + +# RELAX NG schema for the Gentoo Devmanual +# Based on common.dtd from GuideXML + +block.class = p | pre | codesample | note | important | warning | todo +| figure | table | ul | ol | dl +attrib.class = text | b | c | e | sub | sup +inline.class = attrib.class | d | uri + +attrib = attrib.class* +inline = inline.class* +all = (block.class | inline.class)* + +start = guide + +guide = element guide { + (attribute root { "true" } | attribute self { text }), + chapter, + \include* +} + +\include = element include { attribute href { text } } + +chapter = element chapter { title, (body | section), section* } +section = element section { title, (body | subsection), subsection* } +subsection = + element subsection { title, (body | subsubsection), subsubsection* } +subsubsection = element subsubsection { title, body } + +# Title texts are used as anchors, so allow only text attributes +title = element title { attrib } + +body = element body { (authors | contentsTree | block.class)+ } + +authors = element authors { author+ | authorlist+ } + +author = element author { + attribute name { text }, + attribute email { text }?, + inline +} + +authorlist = element authorlist { + attribute title { text }, + attribute href { text } +} + +contentsTree = element contentsTree { + attribute maxdepth { xsd:unsignedInt }?, + attribute root { text }?, + attribute extraction { text }? +} + +p = element p { inline } + +pre = element pre { text } + +codesample = element codesample { + attribute lang { "c" | "ebuild" | "make" | "m4" | "sgml" }, + attribute numbering { "lines" }?, + text +} + +note = element note { inline } +important = element important { inline } +warning = element warning { inline } +todo = element todo { inline } + +figure = element figure { + attribute link { text }, + attribute short { text }?, + attribute caption { text }? +} + +table = element table { tr+ } +tr = element tr { (th | ti)+ } + +th = element th { + attribute colspan { xsd:unsignedInt }?, + attribute rowspan { xsd:unsignedInt }?, + attribute align { "left" | "center" | "right" }?, + inline +} + +ti = element ti { + attribute colspan { xsd:unsignedInt }?, + attribute rowspan { xsd:unsignedInt }?, + attribute nowrap { "nowrap" }?, + attribute align { "left" | "center" | "right" }?, + all +} + +ul = element ul { + attribute class { "list-group" }?, + li+ +} + +ol = element ol { + attribute type { "1" | "A" | "a" | "I" | "i" }?, + li+ +} + +li = element li { all } + +dl = element dl { (dt | dd)+ } +dt = element dt { inline } +dd = element dd { all } + +b = element b { inline } +c = element c { inline } +e = element e { inline } +sub = element sub { inline } +sup = element sup { inline } +d = element d { empty } + +uri = element uri { + # uri can have either a URI in the body text or a link attribute + xsd:anyURI + | (attribute link { text }, inline) +} diff --git a/devbook.rng b/devbook.rng new file mode 100644 index 0000000..3963ab1 --- /dev/null +++ b/devbook.rng @@ -0,0 +1,414 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- Auto-generated from devbook.rnc; do not edit! --> +<grammar xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"> + <!-- + Copyright 2022-2024 Gentoo Authors + Distributed under the terms of the MIT license + or the CC-BY-SA-4.0 license (dual-licensed) + --> + <!-- + RELAX NG schema for the Gentoo Devmanual + Based on common.dtd from GuideXML + --> + <define name="block.class"> + <choice> + <ref name="p"/> + <ref name="pre"/> + <ref name="codesample"/> + <ref name="note"/> + <ref name="important"/> + <ref name="warning"/> + <ref name="todo"/> + <ref name="figure"/> + <ref name="table"/> + <ref name="ul"/> + <ref name="ol"/> + <ref name="dl"/> + </choice> + </define> + <define name="attrib.class"> + <choice> + <text/> + <ref name="b"/> + <ref name="c"/> + <ref name="e"/> + <ref name="sub"/> + <ref name="sup"/> + </choice> + </define> + <define name="inline.class"> + <choice> + <ref name="attrib.class"/> + <ref name="d"/> + <ref name="uri"/> + </choice> + </define> + <define name="attrib"> + <zeroOrMore> + <ref name="attrib.class"/> + </zeroOrMore> + </define> + <define name="inline"> + <zeroOrMore> + <ref name="inline.class"/> + </zeroOrMore> + </define> + <define name="all"> + <zeroOrMore> + <choice> + <ref name="block.class"/> + <ref name="inline.class"/> + </choice> + </zeroOrMore> + </define> + <start> + <ref name="guide"/> + </start> + <define name="guide"> + <element name="guide"> + <choice> + <attribute name="root"> + <value>true</value> + </attribute> + <attribute name="self"/> + </choice> + <ref name="chapter"/> + <zeroOrMore> + <ref name="include"/> + </zeroOrMore> + </element> + </define> + <define name="include"> + <element name="include"> + <attribute name="href"/> + </element> + </define> + <define name="chapter"> + <element name="chapter"> + <ref name="title"/> + <choice> + <ref name="body"/> + <ref name="section"/> + </choice> + <zeroOrMore> + <ref name="section"/> + </zeroOrMore> + </element> + </define> + <define name="section"> + <element name="section"> + <ref name="title"/> + <choice> + <ref name="body"/> + <ref name="subsection"/> + </choice> + <zeroOrMore> + <ref name="subsection"/> + </zeroOrMore> + </element> + </define> + <define name="subsection"> + <element name="subsection"> + <ref name="title"/> + <choice> + <ref name="body"/> + <ref name="subsubsection"/> + </choice> + <zeroOrMore> + <ref name="subsubsection"/> + </zeroOrMore> + </element> + </define> + <define name="subsubsection"> + <element name="subsubsection"> + <ref name="title"/> + <ref name="body"/> + </element> + </define> + <!-- Title texts are used as anchors, so allow only text attributes --> + <define name="title"> + <element name="title"> + <ref name="attrib"/> + </element> + </define> + <define name="body"> + <element name="body"> + <oneOrMore> + <choice> + <ref name="authors"/> + <ref name="contentsTree"/> + <ref name="block.class"/> + </choice> + </oneOrMore> + </element> + </define> + <define name="authors"> + <element name="authors"> + <choice> + <oneOrMore> + <ref name="author"/> + </oneOrMore> + <oneOrMore> + <ref name="authorlist"/> + </oneOrMore> + </choice> + </element> + </define> + <define name="author"> + <element name="author"> + <attribute name="name"/> + <optional> + <attribute name="email"/> + </optional> + <ref name="inline"/> + </element> + </define> + <define name="authorlist"> + <element name="authorlist"> + <attribute name="title"/> + <attribute name="href"/> + </element> + </define> + <define name="contentsTree"> + <element name="contentsTree"> + <optional> + <attribute name="maxdepth"> + <data type="unsignedInt"/> + </attribute> + </optional> + <optional> + <attribute name="root"/> + </optional> + <optional> + <attribute name="extraction"/> + </optional> + </element> + </define> + <define name="p"> + <element name="p"> + <ref name="inline"/> + </element> + </define> + <define name="pre"> + <element name="pre"> + <text/> + </element> + </define> + <define name="codesample"> + <element name="codesample"> + <attribute name="lang"> + <choice> + <value>c</value> + <value>ebuild</value> + <value>make</value> + <value>m4</value> + <value>sgml</value> + </choice> + </attribute> + <optional> + <attribute name="numbering"> + <value>lines</value> + </attribute> + </optional> + <text/> + </element> + </define> + <define name="note"> + <element name="note"> + <ref name="inline"/> + </element> + </define> + <define name="important"> + <element name="important"> + <ref name="inline"/> + </element> + </define> + <define name="warning"> + <element name="warning"> + <ref name="inline"/> + </element> + </define> + <define name="todo"> + <element name="todo"> + <ref name="inline"/> + </element> + </define> + <define name="figure"> + <element name="figure"> + <attribute name="link"/> + <optional> + <attribute name="short"/> + </optional> + <optional> + <attribute name="caption"/> + </optional> + </element> + </define> + <define name="table"> + <element name="table"> + <oneOrMore> + <ref name="tr"/> + </oneOrMore> + </element> + </define> + <define name="tr"> + <element name="tr"> + <oneOrMore> + <choice> + <ref name="th"/> + <ref name="ti"/> + </choice> + </oneOrMore> + </element> + </define> + <define name="th"> + <element name="th"> + <optional> + <attribute name="colspan"> + <data type="unsignedInt"/> + </attribute> + </optional> + <optional> + <attribute name="rowspan"> + <data type="unsignedInt"/> + </attribute> + </optional> + <optional> + <attribute name="align"> + <choice> + <value>left</value> + <value>center</value> + <value>right</value> + </choice> + </attribute> + </optional> + <ref name="inline"/> + </element> + </define> + <define name="ti"> + <element name="ti"> + <optional> + <attribute name="colspan"> + <data type="unsignedInt"/> + </attribute> + </optional> + <optional> + <attribute name="rowspan"> + <data type="unsignedInt"/> + </attribute> + </optional> + <optional> + <attribute name="nowrap"> + <value>nowrap</value> + </attribute> + </optional> + <optional> + <attribute name="align"> + <choice> + <value>left</value> + <value>center</value> + <value>right</value> + </choice> + </attribute> + </optional> + <ref name="all"/> + </element> + </define> + <define name="ul"> + <element name="ul"> + <optional> + <attribute name="class"> + <value>list-group</value> + </attribute> + </optional> + <oneOrMore> + <ref name="li"/> + </oneOrMore> + </element> + </define> + <define name="ol"> + <element name="ol"> + <optional> + <attribute name="type"> + <choice> + <value>1</value> + <value>A</value> + <value>a</value> + <value>I</value> + <value>i</value> + </choice> + </attribute> + </optional> + <oneOrMore> + <ref name="li"/> + </oneOrMore> + </element> + </define> + <define name="li"> + <element name="li"> + <ref name="all"/> + </element> + </define> + <define name="dl"> + <element name="dl"> + <oneOrMore> + <choice> + <ref name="dt"/> + <ref name="dd"/> + </choice> + </oneOrMore> + </element> + </define> + <define name="dt"> + <element name="dt"> + <ref name="inline"/> + </element> + </define> + <define name="dd"> + <element name="dd"> + <ref name="all"/> + </element> + </define> + <define name="b"> + <element name="b"> + <ref name="inline"/> + </element> + </define> + <define name="c"> + <element name="c"> + <ref name="inline"/> + </element> + </define> + <define name="e"> + <element name="e"> + <ref name="inline"/> + </element> + </define> + <define name="sub"> + <element name="sub"> + <ref name="inline"/> + </element> + </define> + <define name="sup"> + <element name="sup"> + <ref name="inline"/> + </element> + </define> + <define name="d"> + <element name="d"> + <empty/> + </element> + </define> + <define name="uri"> + <element name="uri"> + <choice> + <!-- uri can have either a URI in the body text or a link attribute --> + <data type="anyURI"/> + <group> + <attribute name="link"/> + <ref name="inline"/> + </group> + </choice> + </element> + </define> +</grammar> diff --git a/devbook.xsl b/devbook.xsl index 064498d..91feffa 100644 --- a/devbook.xsl +++ b/devbook.xsl @@ -1,9 +1,9 @@ +<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform' xmlns:str="http://exslt.org/strings" xmlns:exslt="http://exslt.org/common" extension-element-prefixes="str exslt xsl" - exclude-result-prefixes="str exslt xsl" - xmlns="http://www.w3.org/1999/xhtml"> + exclude-result-prefixes="str exslt xsl"> <xsl:import href="xsl/str.tokenize.function.xsl"/> <xsl:import href="xsl/lang.highlight.c.xsl"/> @@ -12,726 +12,930 @@ <xsl:import href="xsl/lang.highlight.m4.xsl"/> <xsl:import href="xsl/lang.highlight.sgml.xsl"/> -<xsl:output method="xml" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" - doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" indent="yes"/> +<xsl:output method="html" version="5" encoding="UTF-8" doctype-system="about:legacy-compat"/> + +<!-- When true, disable external assets for offline browsing. + The parameter can be passed with "xsltproc -\-param offline 1". --> +<xsl:param name="offline" select="0"/> <xsl:variable name="newline"> <xsl:text> </xsl:text> </xsl:variable> - <xsl:template match="chapter"> - <h1 class="first-header"><xsl:apply-templates select="title"/></h1> - <xsl:apply-templates select="(body|section)"/> - </xsl:template> - - <xsl:template match="section"> - <div class="section"> - <xsl:variable name="anchor"> - <xsl:call-template name="convert-to-anchor"> - <xsl:with-param name="data" select="title"/> - </xsl:call-template> - </xsl:variable> - - <h2 id="{$anchor}"><xsl:apply-templates select="title"/></h2> - <xsl:apply-templates select="(body|subsection)"/> - </div> - </xsl:template> - - <xsl:template match="subsection"> - <div class="section"> - <xsl:variable name="anchor"> - <xsl:call-template name="convert-to-anchor"> - <xsl:with-param name="data" select="title"/> - </xsl:call-template> - </xsl:variable> - - <h3 id="{$anchor}"><xsl:apply-templates select="title"/></h3> - <xsl:apply-templates select="(body|subsubsection)"/> - - <!-- If you need, change here to add more nesting levels --> - </div> - </xsl:template> - - <xsl:template match="subsubsection"> - <div class="section"> - <xsl:variable name="anchor"> - <xsl:call-template name="convert-to-anchor"> - <xsl:with-param name="data" select="title"/> - </xsl:call-template> - </xsl:variable> - - <h4 id="{$anchor}"><xsl:apply-templates select="title"/></h4> - <xsl:apply-templates select="(body)"/> - - <!-- If you need, change here to add more nesting levels --> - </div> - </xsl:template> - - <xsl:template match="body"> - <xsl:apply-templates/> - </xsl:template> - - <xsl:template match="p"> - <p> +<xsl:template match="chapter"> + <h1 class="first-header"> + <xsl:apply-templates select="title"/> + <a class="permalink" href=""><span class="fa fa-link"/></a> + </h1> + <xsl:apply-templates select="*[not(self::title)]"/> +</xsl:template> + +<xsl:template match="section|subsection|subsubsection"> + <xsl:variable name="level" select="2 + number(starts-with(local-name(), 'sub')) + + number(starts-with(local-name(), 'subsub'))"/> + <xsl:variable name="anchor"> + <xsl:call-template name="convert-to-anchor"> + <xsl:with-param name="data" select="title"/> + </xsl:call-template> + </xsl:variable> + <div class="section"> + <xsl:element name="h{$level}"> + <xsl:attribute name="id"><xsl:value-of select="$anchor"/></xsl:attribute> + <xsl:apply-templates select="title"/> + <a class="permalink" href="#{$anchor}"><span class="fa fa-link"/></a> + </xsl:element> + <xsl:apply-templates select="*[not(self::title)]"/> + </div> +</xsl:template> + +<xsl:template match="body"> + <xsl:apply-templates/> +</xsl:template> + +<xsl:template match="p"> + <p> <xsl:apply-templates/> - </p> - </xsl:template> + </p> +</xsl:template> - <xsl:template match="pre"> +<xsl:template match="pre"> <pre><xsl:apply-templates/></pre> - </xsl:template> +</xsl:template> - <!-- Tables --> - <!-- From the Gentoo GuideXML Stylesheet --> - <xsl:template match="table"> +<!-- Tables --> +<!-- From the Gentoo GuideXML Stylesheet --> +<xsl:template match="table"> <table class="table"><xsl:apply-templates/></table> - </xsl:template> +</xsl:template> - <xsl:template match="tr"> +<xsl:template match="tr"> <tr><xsl:apply-templates/></tr> - </xsl:template> - - <xsl:template match="tcolumn"> - <col width="{@width}"/> - </xsl:template> +</xsl:template> - <!-- Table Item --> - <xsl:template match="ti"> - <td class="devbook"> - <xsl:if test="@colspan"> - <xsl:attribute name="colspan"><xsl:value-of select="@colspan"/></xsl:attribute> - </xsl:if> - <xsl:if test="@rowspan"> - <xsl:attribute name="rowspan"><xsl:value-of select="@rowspan"/></xsl:attribute> - </xsl:if> - <xsl:apply-templates/> - </td> - </xsl:template> - - <!-- Table Heading --> - <xsl:template match="th"> - <th> - <xsl:if test="@colspan"> - <xsl:attribute name="colspan"><xsl:value-of select="@colspan"/></xsl:attribute> - <!-- Center only when item spans several columns as +<!-- Table Item --> +<xsl:template match="ti"> + <td> + <xsl:if test="@colspan"> + <xsl:attribute name="colspan"><xsl:value-of select="@colspan"/></xsl:attribute> + </xsl:if> + <xsl:if test="@rowspan"> + <xsl:attribute name="rowspan"><xsl:value-of select="@rowspan"/></xsl:attribute> + </xsl:if> + <xsl:if test="@nowrap or @align"> + <xsl:attribute name="style"> + <!-- Disable word wrapping for this table item. Usage: <ti nowrap="nowrap"> --> + <xsl:if test="@nowrap">white-space:<xsl:value-of select="@nowrap"/>;</xsl:if> + <xsl:if test="@align">text-align:<xsl:value-of select="@align"/>;</xsl:if> + </xsl:attribute> + </xsl:if> + <xsl:apply-templates/> + </td> +</xsl:template> + +<!-- Table Heading --> +<xsl:template match="th"> + <th> + <xsl:if test="@colspan"> + <xsl:attribute name="colspan"><xsl:value-of select="@colspan"/></xsl:attribute> + </xsl:if> + <xsl:if test="@rowspan"> + <xsl:attribute name="rowspan"><xsl:value-of select="@rowspan"/></xsl:attribute> + </xsl:if> + <xsl:choose> + <xsl:when test="@align"> + <xsl:attribute name="style">text-align:<xsl:value-of select="@align"/>;</xsl:attribute> + </xsl:when> + <xsl:when test="@colspan"> + <!-- Center only when item spans several columns as centering all <th> might disrupt some pages. - We might want to use a plain html <th> tag later. - Tip: to center a single-cell title, use <th colspan="1"> - --> - <xsl:attribute name="style">text-align:center</xsl:attribute> - </xsl:if> - <xsl:if test="@rowspan"> - <xsl:attribute name="rowspan"><xsl:value-of select="@rowspan"/></xsl:attribute> - </xsl:if> - <xsl:apply-templates/> - </th> - </xsl:template> - <!-- End Table Jojo --> - - <!-- FIXME: Handle lang=... --> - <xsl:template match="codesample"> - <xsl:variable name="ctype"><xsl:if test="@lang = 'ebuild'">Constant</xsl:if></xsl:variable> - <xsl:variable name="numbering" select="@numbering"/> - <xsl:variable name="lang" select="@lang"/> - <pre><span class="{$ctype}"> - - <xsl:for-each select="str:tokenize_plasmaroo(., $newline)"> - <xsl:choose> - <xsl:when test=". = $newline"> - <xsl:if test="position() != 1"><xsl:value-of select='$newline'/></xsl:if> - <xsl:if test="$numbering = 'lines' and position() != last()-1"> - <span style="float: left;"><xsl:number format="01"/>:<xsl:text> </xsl:text></span> - </xsl:if> - </xsl:when> - <xsl:otherwise> - <xsl:choose> - <xsl:when test="$lang = 'ebuild'"> - <xsl:call-template name="lang.highlight.ebuild.tokenate"> - <xsl:with-param name="data" select="."/> - </xsl:call-template> - </xsl:when> - <xsl:when test="$lang = 'make'"> - <xsl:call-template name="lang.highlight.make.tokenate"> - <xsl:with-param name="data" select="."/> - </xsl:call-template> - </xsl:when> - <xsl:when test="$lang = 'm4'"> - <xsl:call-template name="lang.highlight.m4.tokenate"> - <xsl:with-param name="data" select="."/> - </xsl:call-template> - </xsl:when> - <xsl:when test="$lang = 'sgml'"> - <xsl:call-template name="lang.highlight.sgml.tokenate"> - <xsl:with-param name="data" select="."/> - </xsl:call-template> - </xsl:when> - <xsl:when test="$lang = 'c'"> - <xsl:call-template name="lang.highlight.c.tokenate"> - <xsl:with-param name="data" select="."/> - </xsl:call-template> - </xsl:when> - <xsl:otherwise> - <xsl:message>Error: Unknown language type (<xsl:value-of select="$lang"/>)</xsl:message> - <xsl:value-of select="."/> - </xsl:otherwise> - </xsl:choose> - </xsl:otherwise> - </xsl:choose> - </xsl:for-each> - </span></pre> - </xsl:template> - - <xsl:template match="figure"> - <div class="figure"> - <div class="image"><img alt="{@short}" src="{@link}"/></div> - <p class="caption"><xsl:value-of select="."/></p> - </div> - </xsl:template> - - <!-- Lists --> - <xsl:template match="li"> - <li><xsl:apply-templates/></li> - </xsl:template> - - <xsl:template match="ol"> - <ol><xsl:apply-templates/></ol> - </xsl:template> - - <xsl:template match="ul"> - <ul><xsl:apply-templates/></ul> - </xsl:template> - - <!-- Definition Lists --> - <xsl:template match="dl"> - <dl><xsl:apply-templates/></dl> - </xsl:template> - - <xsl:template match="dt"> - <dt><xsl:apply-templates/></dt> - </xsl:template> - - <xsl:template match="dd"> - <dd> - <xsl:for-each select="p"> + --> + <xsl:attribute name="style">text-align:center;</xsl:attribute> + </xsl:when> + </xsl:choose> + <xsl:apply-templates/> + </th> +</xsl:template> +<!-- End Table Jojo --> + +<!-- FIXME: Handle lang=... --> +<xsl:template match="codesample"> + <xsl:variable name="ctype"><xsl:if test="@lang = 'ebuild'">Constant</xsl:if></xsl:variable> + <xsl:variable name="numbering" select="@numbering"/> + <xsl:variable name="lang" select="@lang"/> + <pre><span class="{$ctype}"> + + <xsl:for-each select="str:tokenize_plasmaroo(., $newline)"> + <xsl:choose> + <xsl:when test=". = $newline"> + <xsl:if test="position() != 1"><xsl:value-of select='$newline'/></xsl:if> + <xsl:if test="$numbering = 'lines' and position() != last()-1"> + <span style="float: left;"><xsl:number format="01"/>:<xsl:text> </xsl:text></span> + </xsl:if> + </xsl:when> + <xsl:otherwise> + <xsl:choose> + <xsl:when test="$lang = 'ebuild'"> + <xsl:call-template name="lang.highlight.ebuild.tokenate"> + <xsl:with-param name="data" select="."/> + </xsl:call-template> + </xsl:when> + <xsl:when test="$lang = 'make'"> + <xsl:call-template name="lang.highlight.make.tokenate"> + <xsl:with-param name="data" select="."/> + </xsl:call-template> + </xsl:when> + <xsl:when test="$lang = 'm4'"> + <xsl:call-template name="lang.highlight.m4.tokenate"> + <xsl:with-param name="data" select="."/> + </xsl:call-template> + </xsl:when> + <xsl:when test="$lang = 'sgml'"> + <xsl:call-template name="lang.highlight.sgml.tokenate"> + <xsl:with-param name="data" select="."/> + </xsl:call-template> + </xsl:when> + <xsl:when test="$lang = 'c'"> + <xsl:call-template name="lang.highlight.c.tokenate"> + <xsl:with-param name="data" select="."/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:message>Error: Unknown language type (<xsl:value-of select="$lang"/>)</xsl:message> + <xsl:value-of select="."/> + </xsl:otherwise> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> + </xsl:for-each> + </span></pre> +</xsl:template> + +<xsl:template match="figure"> + <div class="figure"> + <div class="image"><img alt="{@short}" src="{@link}"/></div> + <xsl:if test="@caption"> + <p class="caption"><xsl:value-of select="@caption"/></p> + </xsl:if> + </div> +</xsl:template> + +<!-- Lists --> +<xsl:template match="li"> + <li><xsl:apply-templates/></li> +</xsl:template> + +<xsl:template match="ol"> + <ol> + <xsl:if test="@type"> + <xsl:attribute name="style"> + <xsl:text>list-style-type:</xsl:text> <xsl:choose> - <xsl:when test="count(../p) = 1"><xsl:apply-templates/></xsl:when> - <xsl:when test="position() = 1"><p class="first"><xsl:apply-templates/></p></xsl:when> - <xsl:when test="position() = last()"><p class="last"><xsl:apply-templates/></p></xsl:when> - <xsl:otherwise><p><xsl:apply-templates/></p></xsl:otherwise> + <xsl:when test="@type = '1'">decimal</xsl:when> + <xsl:when test="@type = 'A'">upper-alpha</xsl:when> + <xsl:when test="@type = 'a'">lower-alpha</xsl:when> + <xsl:when test="@type = 'I'">upper-roman</xsl:when> + <xsl:when test="@type = 'i'">lower-roman</xsl:when> + <xsl:otherwise><xsl:value-of select="@type"/></xsl:otherwise> </xsl:choose> - </xsl:for-each> - </dd> - </xsl:template> - - <xsl:template match="important"> - <div class="alert alert-info" role="alert"> - <strong>Important:</strong> - <xsl:apply-templates/> - </div> - </xsl:template> - - <xsl:template match="note"> - <div class="alert alert-success" role="alert"> - <strong>Note:</strong> - <xsl:apply-templates/> - </div> - </xsl:template> - - <xsl:template match="todo"> - <div class="alert alert-success" role="alert"> - <strong>Todo:</strong> + </xsl:attribute> + </xsl:if> <xsl:apply-templates/> - </div> - </xsl:template> + </ol> +</xsl:template> + +<xsl:template match="ul"> + <xsl:choose> + <xsl:when test="@class='list-group'"> + <ul class="list-group fix-links"> + <xsl:for-each select="li"> + <li class="list-group-item"> + <xsl:apply-templates> + <xsl:with-param name="class">list-group-item</xsl:with-param> + </xsl:apply-templates> + </li> + </xsl:for-each> + </ul> + </xsl:when> + <xsl:otherwise> + <ul><xsl:apply-templates/></ul> + </xsl:otherwise> + </xsl:choose> +</xsl:template> - <xsl:template match="warning"> - <div class="alert alert-warning" role="alert"> - <strong>Warning:</strong> - <xsl:apply-templates/> - </div> - </xsl:template> +<!-- Definition Lists --> +<xsl:template match="dl"> + <dl><xsl:apply-templates/></dl> +</xsl:template> - <xsl:template match="b"> - <b><xsl:apply-templates/></b> - </xsl:template> +<xsl:template match="dt"> + <dt><xsl:apply-templates/></dt> +</xsl:template> - <xsl:template match="d"> - — - </xsl:template> +<xsl:template match="dd"> + <dd><xsl:apply-templates/></dd> +</xsl:template> - <xsl:template match="e"> - <i><xsl:apply-templates/></i> - </xsl:template> +<xsl:template match="note"> + <div class="alert alert-info" role="alert"> + <strong>Note:</strong><xsl:text> </xsl:text> + <xsl:apply-templates/> + </div> +</xsl:template> - <xsl:template match="c"> - <code class="docutils literal"><span class="pre"><xsl:apply-templates/></span></code> - </xsl:template> +<xsl:template match="important"> + <div class="alert alert-warning" role="alert"> + <strong>Important:</strong><xsl:text> </xsl:text> + <xsl:apply-templates/> + </div> +</xsl:template> - <xsl:template name="convert-to-anchor"> - <xsl:param name="data"/> - <xsl:variable name="lcletters">abcdefghijklmnopqrstuvwxyz--</xsl:variable> - <xsl:variable name="ucletters">ABCDEFGHIJKLMNOPQRSTUVWXYZ<xsl:text> </xsl:text>,</xsl:variable> - <xsl:value-of select="translate($data,$ucletters,$lcletters)"/> - </xsl:template> +<xsl:template match="warning"> + <div class="alert alert-danger" role="alert"> + <strong>Warning:</strong><xsl:text> </xsl:text> + <xsl:apply-templates/> + </div> +</xsl:template> - <xsl:template match="uri"> - <xsl:choose> - <xsl:when test="starts-with(@link, '::')"> - <!-- Ideally we would work out how many levels to nest down to save a few bytes but - going down to root level works just as well (and is faster). --> - <xsl:variable name="relative_path_depth" select="string-length(/guide/@self)-string-length(translate(/guide/@self, '/' , ''))"/> - <xsl:variable name="relative_path_depth_recursion"> - <xsl:call-template name="str:repeatString"> - <xsl:with-param name="count" select="$relative_path_depth"/> - <xsl:with-param name="append">../</xsl:with-param> - </xsl:call-template> - </xsl:variable> +<xsl:template match="todo"> + <div class="alert alert-info" role="alert"> + <strong>Todo:</strong><xsl:text> </xsl:text> + <xsl:apply-templates/> + </div> +</xsl:template> + +<xsl:template match="b"> + <b><xsl:apply-templates/></b> +</xsl:template> + +<xsl:template match="d"> + <xsl:text>—</xsl:text> <!-- em dash --> +</xsl:template> + +<xsl:template match="e"> + <i><xsl:apply-templates/></i> +</xsl:template> + +<xsl:template match="c"> + <code class="docutils literal"><span class="pre"><xsl:apply-templates/></span></code> +</xsl:template> + +<xsl:template match="sub"> + <sub><xsl:apply-templates/></sub> +</xsl:template> + +<xsl:template match="sup"> + <sup><xsl:apply-templates/></sup> +</xsl:template> + +<xsl:template name="convert-to-anchor"> + <xsl:param name="data"/> + <xsl:variable name="lcletters">abcdefghijklmnopqrstuvwxyz-</xsl:variable> + <xsl:variable name="ucletters">ABCDEFGHIJKLMNOPQRSTUVWXYZ<xsl:text> </xsl:text></xsl:variable> + <xsl:variable name="lcdata" select="translate(normalize-space($data), $ucletters, $lcletters)"/> + <!-- Delete anything but letters, digits, hyphen, dot, underscore --> + <xsl:variable name="allowed">abcdefghijklmnopqrstuvwxyz0123456789-._</xsl:variable> + <xsl:value-of select="translate($lcdata, translate($lcdata, $allowed, ''), '')"/> +</xsl:template> + +<xsl:template name="repeat-string"> + <xsl:param name="count"/> + <xsl:param name="append"/> + <xsl:value-of select="str:padding($count * string-length($append), $append)"/> +</xsl:template> + +<xsl:template name="relative-path"> + <xsl:param name="path"/> + <xsl:param name="self"/> + <xsl:choose> + <xsl:when test="$path = '' or $self = '' or substring-before($path, '/') != substring-before($self, '/')"> + <xsl:call-template name="repeat-string"> + <xsl:with-param name="count" select="string-length($self) - string-length(translate($self, '/', ''))"/> + <xsl:with-param name="append">../</xsl:with-param> + </xsl:call-template> + <xsl:value-of select="$path"/> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="relative-path"> + <xsl:with-param name="path" select="substring-after($path, '/')"/> + <xsl:with-param name="self" select="substring-after($self, '/')"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<xsl:template match="uri"> + <xsl:choose> + <!-- Intra-document reference --> + <xsl:when test="starts-with(@link, '::')"> + <xsl:variable name="link_address"> <xsl:choose> - <xsl:when test="contains(@link, '##')"> - <a href="{concat($relative_path_depth_recursion, substring-after(substring-before(@link, '##'), '::'), '/index.html#', substring-after(@link, '##'))}"><xsl:value-of select="."/></a> - </xsl:when> <xsl:when test="contains(@link, '#')"> - <xsl:variable name="anchor"> - <xsl:call-template name="convert-to-anchor"> - <xsl:with-param name="data" select="substring-after(@link, '#')"/> - </xsl:call-template> - </xsl:variable> - <xsl:variable name="slash"> - <xsl:if test="substring(substring-before(@link, '#'), string-length(substring-before(@link, '#'))) != '/'">/</xsl:if> - </xsl:variable> + <xsl:value-of select="substring-before(@link, '#')"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="@link"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <xsl:variable name="path"> + <xsl:value-of select="substring-after($link_address, '::')"/> + <xsl:if test="substring($link_address, string-length($link_address)) != '/'"> + <xsl:message>Warning: No terminating slash in link (<xsl:value-of select="@link"/>)</xsl:message> + <xsl:text>/</xsl:text> + </xsl:if> + </xsl:variable> + <xsl:variable name="path_rel"> + <xsl:call-template name="relative-path"> + <xsl:with-param name="path" select="$path"/> + <xsl:with-param name="self" select="/guide/@self"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="path_html"> + <!-- Omit index.html if referencing an anchor in the same file. --> + <xsl:if test="$path_rel != ''"> + <xsl:value-of select="concat($path_rel, 'index.html')"/> + </xsl:if> + </xsl:variable> + <xsl:choose> + <xsl:when test="contains(@link, '##')"> + <a href="{concat($path_html, '#', substring-after(@link, '##'))}"> + <xsl:value-of select="."/> + </a> + </xsl:when> + <xsl:when test="contains(@link, '#')"> + <xsl:variable name="anchor"> + <xsl:call-template name="convert-to-anchor"> + <xsl:with-param name="data" select="substring-after(@link, '#')"/> + </xsl:call-template> + </xsl:variable> + <a href="{concat($path_html, '#', $anchor)}"> <xsl:choose> <xsl:when test=". != ''"> - <a href="{concat($relative_path_depth_recursion, substring-after(substring-before(@link, '#'), '::'), $slash, 'index.html#', $anchor)}"><xsl:value-of select="."/></a> + <xsl:value-of select="."/> </xsl:when> <xsl:otherwise> - <a href="{concat($relative_path_depth_recursion, substring-after(substring-before(@link, '#'), '::'), $slash, 'index.html#', $anchor)}"><xsl:value-of select="substring-after(@link, '#')"/></a> + <xsl:value-of select="substring-after(@link, '#')"/> </xsl:otherwise> </xsl:choose> - </xsl:when> - <xsl:otherwise> - <xsl:variable name="slash"> - <xsl:if test="substring(@link, string-length(@link)) != '/'">/</xsl:if> - </xsl:variable> + </a> + </xsl:when> + <xsl:otherwise> + <a href="{$path_html}"> <xsl:choose> <xsl:when test=". != ''"> - <a href="{concat($relative_path_depth_recursion, substring-after(@link, '::'), $slash, 'index.html')}"><xsl:value-of select="."/></a> + <xsl:value-of select="."/> + </xsl:when> + <xsl:when test="starts-with($path, 'eclass-reference/') and substring-after($path, '/') != ''"> + <!-- Eclass reference pages are generated with man2html, + so there isn't any text.xml that could be loaded. + Use the name of the eclass as link text. #442194 --> + <xsl:value-of select="substring-before(substring-after($path, '/'), '/')"/> </xsl:when> <xsl:otherwise> - <a href="{concat($relative_path_depth_recursion, substring-after(@link, '::'), $slash, 'index.html')}"><xsl:value-of select="document(concat(/guide/@self, $relative_path_depth_recursion, substring-after(@link, '::'), '/text.xml'))/guide/chapter[1]/title"/></a> + <xsl:value-of select="document(concat($path, 'text.xml'))/guide/chapter[1]/title"/> </xsl:otherwise> </xsl:choose> - </xsl:otherwise> - </xsl:choose> - </xsl:when> - <xsl:otherwise> - <a href="{@link}"><xsl:value-of select="."/></a> - </xsl:otherwise> - </xsl:choose> - </xsl:template> - - <!-- TOC Tree --> - <xsl:template match="contentsTree" name="contentsTree"> - <xsl:param name="depth" select="0"/> - <xsl:param name="ulclass"/> - <xsl:param name="maxdepth"> - <xsl:choose> - <xsl:when test="@maxdepth"><xsl:value-of select="@maxdepth"/></xsl:when> - <xsl:otherwise>0</xsl:otherwise> + </a> + </xsl:otherwise> </xsl:choose> - </xsl:param> - <xsl:param name="path"> - <xsl:choose> - <xsl:when test="@root"><xsl:value-of select="@root"/></xsl:when> - <xsl:otherwise><xsl:value-of select="/guide/@self"/></xsl:otherwise> - </xsl:choose> - </xsl:param> - <xsl:param name="path_rel"> - <xsl:if test="$depth = 0 and $path = '' and /guide/@self != ''"> - <xsl:call-template name="str:repeatString"> - <xsl:with-param name="count" select="string-length(/guide/@self)-string-length(translate(/guide/@self, '/' , ''))"/> - <xsl:with-param name="append">../</xsl:with-param> - </xsl:call-template> - </xsl:if> - </xsl:param> - <xsl:param name="extraction" select="@extraction"/> - <xsl:param name="extraction_counting"/> + </xsl:when> + <!-- External reference, URI in link attribute --> + <xsl:when test="@link"> + <a href="{@link}"><xsl:value-of select="."/></a> + </xsl:when> + <!-- External reference, URI in body text --> + <xsl:when test="contains(., '://')"> + <a href="{.}"><xsl:value-of select="."/></a> + </xsl:when> + <xsl:otherwise> + <xsl:message>Error: No link target (<xsl:value-of select="."/>)</xsl:message> + <a><xsl:value-of select="."/></a> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<!-- TOC Tree --> +<xsl:template match="contentsTree" name="contentsTree"> + <xsl:param name="depth" select="0"/> + <xsl:param name="maxdepth"> + <xsl:choose> + <xsl:when test="@maxdepth"><xsl:value-of select="@maxdepth"/></xsl:when> + <xsl:otherwise>0</xsl:otherwise> + </xsl:choose> + </xsl:param> + <xsl:param name="path"> + <xsl:choose> + <xsl:when test="@root"><xsl:value-of select="@root"/></xsl:when> + <xsl:otherwise><xsl:value-of select="/guide/@self"/></xsl:otherwise> + </xsl:choose> + </xsl:param> + <xsl:param name="path_rel"> + <xsl:if test="$depth = 0 and $path = '' and /guide/@self != ''"> + <xsl:call-template name="repeat-string"> + <xsl:with-param name="count" + select="string-length(/guide/@self) - string-length(translate(/guide/@self, '/' , ''))"/> + <xsl:with-param name="append">../</xsl:with-param> + </xsl:call-template> + </xsl:if> + </xsl:param> + <xsl:param name="orig_self" select="/guide/@self"/> + <xsl:param name="extraction" select="@extraction"/> + <xsl:param name="extraction_counting"/> - <xsl:variable name="doc_self" select="concat($path, 'text.xml')"/> - <xsl:if test="count(document($doc_self)/guide/include) > 0 and ($depth < $maxdepth or $maxdepth = '0')"> + <xsl:variable name="doc_self" select="concat($path, 'text.xml')"/> + <xsl:if test="count(document($doc_self)/guide/include) > 0 and ($depth < $maxdepth or $maxdepth = '0')"> <xsl:choose> <xsl:when test="$extraction_counting = 1"> - <xsl:for-each select="document($doc_self)/guide/include"> - <count value="{count(document(concat($path, @href, 'text.xml'))//*[name()=$extraction])}" path="{concat($path, @href)}"> - <xsl:call-template name="contentsTree"> - <xsl:with-param name="depth" select="$depth + 1"/> - <xsl:with-param name="maxdepth" select="$maxdepth"/> - <xsl:with-param name="path" select="concat($path, @href)"/> - <xsl:with-param name="path_rel" select="concat($path_rel, @href)"/> - <xsl:with-param name="extraction" select="$extraction"/> - <xsl:with-param name="extraction_counting" select="1"/> - </xsl:call-template> - </count> - </xsl:for-each> + <xsl:for-each select="document($doc_self)/guide/include"> + <count value="{count(document(concat($path, @href, 'text.xml'))//*[name()=$extraction])}" + path="{concat($path, @href)}"> + <xsl:call-template name="contentsTree"> + <xsl:with-param name="depth" select="$depth + 1"/> + <xsl:with-param name="maxdepth" select="$maxdepth"/> + <xsl:with-param name="path" select="concat($path, @href)"/> + <xsl:with-param name="path_rel" select="concat($path_rel, @href)"/> + <xsl:with-param name="orig_self" select="$orig_self"/> + <xsl:with-param name="extraction" select="$extraction"/> + <xsl:with-param name="extraction_counting" select="1"/> + </xsl:call-template> + </count> + </xsl:for-each> </xsl:when> <xsl:otherwise> - <ul class="{$ulclass}"> - <xsl:for-each select="document($doc_self)/guide/include"> - <xsl:variable name="extraction_counter_node"> - <xsl:call-template name="contentsTree"> - <xsl:with-param name="depth" select="$depth + 1"/> - <xsl:with-param name="maxdepth" select="$maxdepth"/> - <xsl:with-param name="path" select="concat($path, @href)"/> - <xsl:with-param name="path_rel" select="concat($path_rel, @href)"/> - <xsl:with-param name="extraction" select="$extraction"/> - <xsl:with-param name="extraction_counting" select="1"/> - </xsl:call-template> - </xsl:variable> - <xsl:variable name="extraction_counter" select="count(exslt:node-set($extraction_counter_node)//*[@value != 0]) + count(document(concat($path, @href, 'text.xml'))//*[name()=$extraction])"/> - <xsl:if test="string($extraction) = '' or $extraction_counter > 0"> - <li> - <a class="reference" href="{concat($path_rel, @href, 'index.html')}"><xsl:value-of select="document(concat($path, @href, 'text.xml'))/guide/chapter[1]/title"/></a> - <xsl:if test="$extraction != ''"> - <ul> - <xsl:for-each select="document(concat($path, @href, 'text.xml'))//*[name()=$extraction]"> - <xsl:variable name="extraction_id" select="position()"/> - <li><xsl:apply-templates select="(//*[name()=$extraction])[position()=$extraction_id]"/><br/></li> - </xsl:for-each> - </ul> - </xsl:if> - <xsl:call-template name="contentsTree"> - <xsl:with-param name="depth" select="$depth + 1"/> - <xsl:with-param name="maxdepth" select="$maxdepth"/> - <xsl:with-param name="path" select="concat($path, @href)"/> - <xsl:with-param name="path_rel" select="concat($path_rel, @href)"/> - <xsl:with-param name="extraction" select="$extraction"/> - </xsl:call-template> - </li> - </xsl:if> - </xsl:for-each> - </ul> + <ul> + <xsl:for-each select="document($doc_self)/guide/include"> + <xsl:variable name="extraction_counter_node"> + <xsl:call-template name="contentsTree"> + <xsl:with-param name="depth" select="$depth + 1"/> + <xsl:with-param name="maxdepth" select="$maxdepth"/> + <xsl:with-param name="path" select="concat($path, @href)"/> + <xsl:with-param name="path_rel" select="concat($path_rel, @href)"/> + <xsl:with-param name="orig_self" select="$orig_self"/> + <xsl:with-param name="extraction" select="$extraction"/> + <xsl:with-param name="extraction_counting" select="1"/> + </xsl:call-template> + </xsl:variable> + <xsl:variable name="extraction_counter" + select="count(exslt:node-set($extraction_counter_node)//*[@value != 0]) + + count(document(concat($path, @href, 'text.xml'))//*[name()=$extraction])"/> + <xsl:if test="string($extraction) = '' or $extraction_counter > 0"> + <li> + <a class="reference" href="{concat($path_rel, @href, 'index.html')}"> + <xsl:value-of select="document(concat($path, @href, 'text.xml'))/guide/chapter[1]/title"/> + </a> + <xsl:if test="$extraction != ''"> + <!-- If the extracted element from the other document contains + any internal references, relative links would be based on + the wrong start location. So we must replace /guide/@self + by our own copy. Bug #916523. --> + <xsl:variable name="document_tree"> + <guide self="{$orig_self}"> + <xsl:copy-of select="document(concat($path, @href, 'text.xml'))/guide/*"/> + </guide> + </xsl:variable> + <ul> + <xsl:for-each select="exslt:node-set($document_tree)//*[name()=$extraction]"> + <li><xsl:apply-templates select="."/></li> + </xsl:for-each> + </ul> + </xsl:if> + <xsl:call-template name="contentsTree"> + <xsl:with-param name="depth" select="$depth + 1"/> + <xsl:with-param name="maxdepth" select="$maxdepth"/> + <xsl:with-param name="path" select="concat($path, @href)"/> + <xsl:with-param name="path_rel" select="concat($path_rel, @href)"/> + <xsl:with-param name="orig_self" select="$orig_self"/> + <xsl:with-param name="extraction" select="$extraction"/> + </xsl:call-template> + </li> + </xsl:if> + </xsl:for-each> + </ul> </xsl:otherwise> </xsl:choose> - </xsl:if> - </xsl:template> - - <xsl:template match="/"> - <html lang="en-GB" xml:lang="en-GB" xmlns="http://www.w3.org/1999/xhtml"> + </xsl:if> +</xsl:template> + +<xsl:template match="/"> + <xsl:variable name="relative_path_depth_recursion"> + <xsl:call-template name="repeat-string"> + <xsl:with-param name="count" select="string-length(/guide/@self) + - string-length(translate(/guide/@self, '/' , ''))"/> + <xsl:with-param name="append">../</xsl:with-param> + </xsl:call-template> + </xsl:variable> + <html lang="en"> <head> - <title>Gentoo Development Guide: <xsl:value-of select="/guide/chapter[1]/title"/></title> - <xsl:variable name="relative_path_depth" select="string-length(/guide/@self)-string-length(translate(/guide/@self, '/' , ''))"/> - <xsl:variable name="relative_path_depth_recursion"> - <xsl:call-template name="str:repeatString"> - <xsl:with-param name="count" select="$relative_path_depth"/> - <xsl:with-param name="append">../</xsl:with-param> - </xsl:call-template> - </xsl:variable> - <link rel="stylesheet" href="{$relative_path_depth_recursion}devmanual.css" type="text/css" /> - <meta charset="utf-8" /> + <title><xsl:value-of select="/guide/chapter[1]/title"/> – Gentoo Development Guide</title> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta name="description" content="Gentoo Infrastructure Status provides information on the status of the services the Gentoo Linux distribution offers to its developers and users." /> - <link href="https://1b9a50f4f9de4348cd9f-e703bc50ba0aa66772a874f8c7698be7.ssl.cf5.rackcdn.com/bootstrap.min.css" rel="stylesheet" media="screen" /> - <link href="https://1b9a50f4f9de4348cd9f-e703bc50ba0aa66772a874f8c7698be7.ssl.cf5.rackcdn.com/tyrian.min.css" rel="stylesheet" media="screen" /> - <link rel="icon" href="http://www.gentoo.org/favicon.ico" type="image/x-icon" /> + <meta name="description" content="The Gentoo Devmanual is a technical manual which covers topics such as writing ebuilds and eclasses, and policies that developers should be abiding by." /> + <xsl:choose> + <xsl:when test="$offline"> + <link rel="stylesheet" href="{$relative_path_depth_recursion}offline.css" type="text/css" /> + </xsl:when> + <xsl:otherwise> + <link href="https://assets.gentoo.org/tyrian/bootstrap.min.css" rel="stylesheet" media="screen" /> + <link href="https://assets.gentoo.org/tyrian/tyrian.min.css" rel="stylesheet" media="screen" /> + </xsl:otherwise> + </xsl:choose> + <link rel="stylesheet" href="{$relative_path_depth_recursion}devmanual.css" type="text/css" /> + <link rel="icon" href="https://www.gentoo.org/favicon.ico" type="image/x-icon" /> </head> <body> <header> - <div class="site-title"> - <div class="container"> - <div class="row"> - <div class="site-title-buttons"> - <div class="btn-group btn-group-sm"> - <a href="http://get.gentoo.org/" type="button" class="btn get-gentoo"><span class="fa fa-download"></span> <strong>Get Gentoo!</strong></a> - <div class="btn-group btn-group-sm"> - <button type="button" class="gentoo-org-sites btn" data-toggle="dropdown"> - <span class="glyphicon glyphicon-globe"></span> gentoo.org sites <span class="caret"></span> + <xsl:choose> + <xsl:when test="$offline"> + <nav class="offline"> + <ul> + <li><xsl:call-template name="findPrevious"/></li> + <li><xsl:call-template name="findNext"/></li> + </ul> + </nav> + </xsl:when> + <xsl:otherwise> + <div class="site-title"> + <div class="container"> + <div class="row"> + <div class="site-title-buttons"> + <div class="btn-group btn-group-sm"> + <a href="https://get.gentoo.org/" role="button" class="btn get-gentoo"><span class="fa fa-fw fa-download"></span> <strong> Get Gentoo!</strong></a> + <div class="btn-group btn-group-sm"> + <a class="btn gentoo-org-sites dropdown-toggle" data-toggle="dropdown" data-target="#" href="#"> + <span class="fa fa-fw fa-map-o"></span> <span class="hidden-xs"> gentoo.org sites </span> <span class="caret"></span> + </a> + <ul class="dropdown-menu dropdown-menu-right"> + <li><a href="https://www.gentoo.org/" title="Main Gentoo website"><span class="fa fa-home fa-fw"></span> gentoo.org</a></li> + <li><a href="https://wiki.gentoo.org/" title="Find and contribute documentation"><span class="fa fa-file-text-o fa-fw"></span> Wiki</a></li> + <li><a href="https://bugs.gentoo.org/" title="Report issues and find common issues"><span class="fa fa-bug fa-fw"></span> Bugs</a></li> + <li><a href="https://forums.gentoo.org/" title="Discuss with the community"><span class="fa fa-comments-o fa-fw"></span> Forums</a></li> + <li><a href="https://packages.gentoo.org/" title="Find software for your Gentoo"><span class="fa fa-hdd-o fa-fw"></span> Packages</a></li> + <li class="divider"><xsl:comment/></li> + <li><a href="https://planet.gentoo.org/" title="Find out what's going on in the developer community"><span class="fa fa-rss fa-fw"></span> Planet</a></li> + <li><a href="https://archives.gentoo.org/" title="Read up on past discussions"><span class="fa fa-archive fa-fw"></span> Archives</a></li> + <li><a href="https://sources.gentoo.org/" title="Browse our source code"><span class="fa fa-code fa-fw"></span> Sources</a></li> + <li class="divider"><xsl:comment/></li> + <li><a href="https://infra-status.gentoo.org/" title="Get updates on the services provided by Gentoo"><span class="fa fa-server fa-fw"></span> Infra Status</a></li> + </ul> + </div> + </div> + </div> + <div> + <a href="/" title="Back to the homepage" class="site-logo"> + <object data="https://assets.gentoo.org/tyrian/site-logo.svg" type="image/svg+xml"> + <img src="https://assets.gentoo.org/tyrian/site-logo.png" alt="Gentoo Linux Logo" /> + </object> + </a> + <span class="site-label">Development Guide</span> + </div> + </div> + </div> + </div> + <nav class="tyrian-navbar" role="navigation"> + <div class="container"> + <div class="row"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle" + data-toggle="collapse" data-target=".navbar-main-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> </button> - <ul class="dropdown-menu"> - <li><a href="http://www.gentoo.org/" title="Main Gentoo website"><span class="fa fa-home fa-fw"></span> gentoo.org</a></li> - <li><a href="http://wiki.gentoo.org/" title="Find and contribute documentation"><span class="fa fa-file-text fa-fw"></span> Wiki</a></li> - <li><a href="https://bugs.gentoo.org/" title="Report issues and find common issues"><span class="fa fa-bug fa-fw"></span> Bugs</a></li> - <li><a href="http://forums.gentoo.org/" title="Discuss with the community"><span class="fa fa-comments-o fa-fw"></span> Forums</a></li> - <li><a href="http://packages.gentoo.org/" title="Find software for your Gentoo"><span class="fa fa-hdd-o fa-fw"></span> Packages</a></li> - <li class="divider"></li> - <li><a href="http://overlays.gentoo.org/" title="Collaborate on maintaining packages"><span class="fa fa-code-fork fa-fw"></span> Overlays</a></li> - <li><a href="http://planet.gentoo.org/" title="Find out what's going on in the developer community"><span class="fa fa-rss fa-fw"></span> Planet</a></li> - <li><a href="http://archives.gentoo.org/" title="Read up on past discussions"><span class="fa fa-archive fa-fw"></span> Archives</a></li> - <li><a href="http://sources.gentoo.org/" title="Browse our source code"><span class="fa fa-code fa-fw"></span> Sources</a></li> - <li class="divider"></li> - <li><a href="http://infra-status.gentoo.org/" title="Get updates on the services provided by Gentoo"><span class="fa fa-tasks fa-fw"></span> Infra Status</a></li> + </div> + <div class="collapse navbar-collapse navbar-main-collapse"> + <ul class="nav navbar-nav"> + <li> + <a href="{$relative_path_depth_recursion}index.html"><span class="fa fa-home"/> Home</a> + </li> + <li class="dropdown"> + <a href="#" class="dropdown-toggle" data-toggle="dropdown">Index <span class="caret"></span></a> + <xsl:if test="/guide/chapter[1]/section or //contentsTree"> + <ul class="dropdown-menu"> + <!-- List sections of this chapter first. --> + <xsl:for-each select="/guide/chapter[1]/section"> + <xsl:variable name="anchor"> + <xsl:call-template name="convert-to-anchor"> + <xsl:with-param name="data" select="title"/> + </xsl:call-template> + </xsl:variable> + <li><a class="reference" href="#{$anchor}"><xsl:value-of select="title"/></a></li> + </xsl:for-each> + <xsl:if test="//contentsTree"> + <li class="divider"></li> + <!-- List any sub-documents included at first level. + We cannot call "contentsTree" directly, because it would + insert another "ul" element. So, assign it to a variable, + then copy only the "li" nodes. --> + <xsl:variable name="contents"> + <xsl:call-template name="contentsTree"> + <xsl:with-param name="maxdepth" select="1"/> + </xsl:call-template> + </xsl:variable> + <xsl:copy-of select="exslt:node-set($contents)/ul/li"/> + </xsl:if> + </ul> + </xsl:if> + </li> + <li><xsl:call-template name="findPrevious"/></li> + <li><xsl:call-template name="findNext"/></li> </ul> </div> </div> </div> - <div class="logo"> - <img src="https://1b9a50f4f9de4348cd9f-e703bc50ba0aa66772a874f8c7698be7.ssl.cf5.rackcdn.com/site-logo.png" alt="Gentoo Linux Logo"/> - <span class="site-label">Gentoo Development Guide</span> - </div> - </div> - </div> - </div> - <nav class="tyrian-navbar" role="navigation"> - <div class="container"> - <div class="row"> - <div class="navbar-header"> - <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-main-collapse"> - <span class="sr-only">Toggle navigation</span> - <span class="icon-bar"></span> - <span class="icon-bar"></span> - <span class="icon-bar"></span> - </button> + </nav> + <nav class="navbar navbar-grey navbar-stick" id="devmanual-actions" role="navigation"> + <div class="container"> + <div class="row"> + <div class="input-group"> + <input type="search" name="search" placeholder="Search" title="Search Gentoo Developer Manual [f]" + accesskey="f" id="searchInput" class="form-control" onclick="fetchDocuments()"/> + <div class="input-group-btn"> + <input type="submit" name="fulltext" value="Search" title="Search the pages for this text" + id="mw-searchButton" class="searchButton btn btn-default" onclick="search()"/> + </div> + </div> + </div> </div> - <div class="collapse navbar-collapse navbar-main-collapse"> - <ul class="nav navbar-nav"> - <xsl:variable name="relative_path_depth" select="string-length(/guide/@self)-string-length(translate(/guide/@self, '/' , ''))"/> - <xsl:variable name="relative_path_depth_recursion"> - <xsl:call-template name="str:repeatString"> - <xsl:with-param name="count" select="$relative_path_depth"/> - <xsl:with-param name="append">../</xsl:with-param> - </xsl:call-template> - </xsl:variable> - <li><a href="{concat($relative_path_depth_recursion, substring-after(substring-before(@link, '##'), '::'), '/index.html', substring-after(@link, '##'))}"><span class="glyphicon glyphicon-home"/>  Home</a></li> - <li class="dropdown"> - <a href="#" class="dropdown-toggle" data-toggle="dropdown"><xsl:value-of select="/guide/chapter[1]/title"/> <span class="caret"></span></a> - <xsl:call-template name="contentsTree"> - <xsl:with-param name="maxdepth" select="1"/> - <xsl:with-param name="ulclass">dropdown-menu</xsl:with-param> - </xsl:call-template> - </li> - <li><xsl:call-template name="findPrevious"/></li> - <li><xsl:call-template name="findNext"/></li> - </ul> + </nav> + <div id="searchResults" class="modal fade" role="dialog"> + <div class="modal-dialog"> + <div class="modal-content"> + <div class="modal-header"> + <button type="button" class="close" data-dismiss="modal">x</button> + <h4 class="modal-title">Search Results</h4> + </div> + <div class="modal-body"> + <p>No results found.</p> + </div> + <div class="modal-footer"> + <button type="button" class="btn btn-default" data-dismiss="modal">Close</button> + </div> + </div> </div> </div> + </xsl:otherwise> + </xsl:choose> + <div class="container"> + <div class="row"> + <div class="col-md010"> + <ol class="breadcrumb"> + <xsl:call-template name="printParentDocs"/> + </ol> + </div> </div> - </nav> + </div> </header> - <div class="container"> - <div class="row"> - <div class="col-md010"> - <ol class="breadcrumb"> - <xsl:call-template name="printParentDocs"> - <xsl:with-param name="path" select="/guide/@self"/> - <xsl:with-param name="depth" select="string-length(/guide/@self)-string-length(translate(/guide/@self, '/' , ''))"/> - </xsl:call-template> - </ol> - </div> + <main> + <div class="container"> + <xsl:apply-templates/> </div> - </div> - <div class="container"> - <xsl:apply-templates/> - </div> + </main> <footer> <div class="container"> - <div class="row"> - <div class="col-md-8"> - </div> - <div class="col-md-4"> - <strong>Questions or comments?</strong><br /> - Please feel free to <a href="http://www.gentoo.org/main/en/contact.xml">contact us</a>. + <xsl:if test="not($offline)"> + <div class="row"> + <div class="col-xs-12 col-md-offset-2 col-md-7"> + </div> + <div class="col-xs-12 col-md-3"> + <h3 class="footerhead">Questions or comments?</h3> + Please feel free to <a href="https://www.gentoo.org/inside-gentoo/contact/">contact us</a>. + </div> </div> - </div> + </xsl:if> <div class="row"> - <div class="col-md-12"> - <strong>Copyright 2001-2014 Gentoo Foundation, Inc.</strong><br /> + <div class="col-xs-2 col-sm-3 col-md-2"> + <xsl:if test="not($offline)"> + <ul class="footerlinks three-icons"> + <li><a href="https://twitter.com/gentoo" title="@Gentoo on Twitter"><span class="fa fa-twitter fa-fw"></span></a></li> + <li><a href="https://www.facebook.com/gentoo.org" title="Gentoo on Facebook"><span class="fa fa-facebook fa-fw"></span></a></li> + </ul> + <div class="text-center"> + <a href="https://wiki.gentoo.org/wiki/Foundation:Privacy_Policy">Privacy Policy</a> + </div> + </xsl:if> + </div> + <div class="col-xs-10 col-sm-9 col-md-10"> + <strong>Copyright (C) 2001-2024 Gentoo Authors</strong><br /> <small> - Gentoo is a trademark of the Gentoo Foundation, Inc. - The text of this document is distributed under the <a href="http://creativecommons.org/licenses/by-sa/2.0/">Creative Commons Attribution-ShareAlike 2.0 License</a>. - The <a href="http://www.gentoo.org/main/en/name-logo.xml">Gentoo Name and Logo Usage Guidelines</a> apply. + Gentoo is a trademark of the Gentoo Foundation, Inc. and of Förderverein Gentoo e.V. + The text of this document is distributed under the + <xsl:choose> + <!-- Eclasses are GPL-2, so we need a different footer --> + <xsl:when test="starts-with(/guide/@self, 'eclass-reference/') + and substring-after(/guide/@self, '/') != ''"> + <a href="https://www.gnu.org/licenses/gpl-2.0.html">GNU General Public License, version 2</a>. + </xsl:when> + <xsl:otherwise> + <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>. + </xsl:otherwise> + </xsl:choose> + The <a href="https://www.gentoo.org/inside-gentoo/foundation/name-logo-guidelines.html">Gentoo Name and Logo Usage Guidelines</a> apply. </small> </div> </div> </div> </footer> - <script src="https://1b9a50f4f9de4348cd9f-e703bc50ba0aa66772a874f8c7698be7.ssl.cf5.rackcdn.com/jquery.min.js"></script> - <script src="https://1b9a50f4f9de4348cd9f-e703bc50ba0aa66772a874f8c7698be7.ssl.cf5.rackcdn.com/bootstrap.min.js"></script> + <xsl:if test="not($offline)"> + <script src="https://assets.gentoo.org/tyrian/jquery.min.js"></script> + <script src="https://assets.gentoo.org/tyrian/bootstrap.min.js"></script> + <script src="https://assets.gentoo.org/lunr/lunr.min.js"></script> + <script>var documentsSrc = "<xsl:value-of select="$relative_path_depth_recursion"/>documents.js"</script> + <script src="{$relative_path_depth_recursion}search.js"></script> + </xsl:if> </body> - </html> - </xsl:template> - - <xsl:template name="str:repeatString"> - <xsl:param name="string"/> - <xsl:param name="count"/> - <xsl:param name="append"/> - <xsl:choose> - <xsl:when test="$count != 0"> - <xsl:call-template name="str:repeatString"> - <xsl:with-param name="string" select="concat($string, $append)"/> - <xsl:with-param name="count" select="$count - 1"/> - <xsl:with-param name="append" select="$append"/> + </html> +</xsl:template> + +<xsl:template name="findNext"> + <xsl:param name="self" select="/guide/@self"/> + <xsl:choose> + <!-- To find the "next" node: + * See if this node includes any subnodes... if it does, that is + our next node + * Look at our parent and see if it includes any nodes after us, + if it does use it. + * Repeat recursively, going down parents if needed. + * End at the root item if needed. + --> + <xsl:when test="count(/guide/include) > 0"> + <xsl:variable name="doc" select="/guide/include[1]/@href"/> + <a class="w-250 text-center" href="{concat($doc, 'index.html')}"> + <span class="truncated-text d-inline-block max-w-200 mr-2"> + <xsl:value-of select="document(concat(/guide/@self, $doc, 'text.xml'))/guide/chapter[1]/title"/> + </span> + <span class="fa fa-arrow-right"/> + </a> + </xsl:when> + <xsl:otherwise> + <!-- Turn the absolute path into a relative path so we can find ourselves + in the parent --> + <xsl:variable name="path_self" select="concat(str:tokenize($self, '/')[last()], '/')"/> + <xsl:variable name="index_self" + select="count(document(concat($self, '../text.xml'))/guide/include[@href=$path_self]/preceding-sibling::*)+1"/> + <!-- Go down a parent, lookup the item after us... --> + <xsl:variable name="parentItem_lookup" + select="document(concat($self, '../text.xml'))/guide/include[$index_self]/@href"/> + <xsl:variable name="parentItem_next" + select="concat(document(concat($self, '../text.xml'))/guide/@self, $parentItem_lookup)"/> + <xsl:choose> + <!-- If we have an item after us, or we are at the root node + (termination condition) we need to not recurse any further... --> + <xsl:when test="$parentItem_lookup != '' or document(concat($self, '../text.xml'))/guide/@root"> + <!-- Compute a relative path for the link. --> + <xsl:variable name="path_rel"> + <xsl:call-template name="relative-path"> + <xsl:with-param name="path" select="$parentItem_next"/> + <xsl:with-param name="self" select="/guide/@self"/> + </xsl:call-template> + </xsl:variable> + <a class="w-250 text-center" href="{concat($path_rel, 'index.html')}"> + <span class="truncated-text d-inline-block max-w-200 mr-2"> + <xsl:value-of select="document(concat($parentItem_next, 'text.xml'))/guide/chapter[1]/title"/> + </span> + <span class="fa fa-arrow-right"/> + </a> + </xsl:when> + <xsl:otherwise> + <!-- We need to recurse downwards; so we need to strip off a directory + element off our absolute path to feed into the next iteration... --> + <xsl:variable name="relative_path_fixed"> + <xsl:for-each select="str:tokenize($self, '/')[position() < last()]"> + <xsl:value-of select="concat(., '/')"/> + </xsl:for-each> + </xsl:variable> + <xsl:call-template name="findNext"> + <xsl:with-param name="self" select="$relative_path_fixed"/> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +<xsl:template name="getLastNode"> + <!-- This function recurses forward down nodes stopping at the very last include... --> + <xsl:param name="root"/> + <xsl:param name="path"/> + <xsl:variable name="include" select="document(concat($root, $path, 'text.xml'))/guide/include[last()]/@href"/> + <xsl:choose> + <xsl:when test="$include"> + <xsl:call-template name="getLastNode"> + <xsl:with-param name="root" select="$root"/> + <xsl:with-param name="path" select="concat($path, $include)"/> </xsl:call-template> </xsl:when> <xsl:otherwise> - <xsl:value-of select="$string"/> + <xsl:value-of select="$path"/> </xsl:otherwise> - </xsl:choose> - </xsl:template> - - <xsl:template name="findNext"> - <xsl:param name="self" select="/guide/@self"/> - <xsl:choose> - <!-- To find the "next" node: - * See if this node includes any subnodes... if it does, that is - our next node - * Look at our parent and see if it includes any nodes after us, if - it does use it. - * Repeat recursively, going down parents if needed. - * End at the root item if needed. - --> - <xsl:when test="count(/guide/include) > 0"> - <xsl:variable name="doc" select="/guide/include[1]/@href"/> - <a href="{concat($doc, 'index.html')}"><xsl:value-of select="document(concat(/guide/@self, $doc, 'text.xml'))/guide/chapter[1]/title"/>  <span class="glyphicon glyphicon-arrow-right"/></a> - </xsl:when> - <xsl:otherwise> - <!-- This document's path --> - <xsl:variable name="doc_self" select="concat($self, 'text.xml')"/> - <!-- Turn the absolute path into a relative path so we can find ourselves in - the parent --> - <xsl:variable name="path_self" select="concat(str:tokenize($self, '/')[last()], '/')"/> - <xsl:variable name="index_self" select="count(document(concat($self, '../text.xml'))/guide/include[@href=$path_self]/preceding-sibling::*)+1"/> - <!-- Go down a parent, lookup the item after us... --> - <xsl:variable name="parentItem_lookup" select="document(concat($self, '../text.xml'))/guide/include[$index_self]/@href"/> - <xsl:variable name="parentItem_next" select="concat(document(concat($self, '../text.xml'))/guide/@self, $parentItem_lookup)"/> - <xsl:choose> - <!-- If we have an item after us, or we are at the root node (termination condition) we need to - not recurse any further... --> - <xsl:when test="$parentItem_lookup != '' or document(concat($self, '../text.xml'))/guide/@root"> - <xsl:variable name="parentItem_actual"> - <xsl:choose> - <xsl:when test="$parentItem_next = ''"></xsl:when> - <xsl:otherwise><xsl:value-of select="$parentItem_next"/></xsl:otherwise> - </xsl:choose> - </xsl:variable> - <!-- This is where we do a little trickery. To count how many levels we need to go down, - we count how far up we currently are (remember that the absolute link we get is relative to /...) and - hence we can build a relative link... --> - <xsl:variable name="relative_path" select="$parentItem_actual"/> - <xsl:variable name="relative_path_depth" select="string-length(/guide/@self)-string-length(translate(/guide/@self, '/' , ''))"/> - <xsl:variable name="relative_path_depth_recursion"> - <xsl:call-template name="str:repeatString"> - <xsl:with-param name="count" select="$relative_path_depth"/> - <xsl:with-param name="append">../</xsl:with-param> - </xsl:call-template> - </xsl:variable> - <a href="{concat($relative_path_depth_recursion, $relative_path, 'index.html')}"><xsl:value-of select="document(concat($parentItem_actual, 'text.xml'))/guide/chapter[1]/title"/>  <span class="glyphicon glyphicon-arrow-right"/></a> - </xsl:when> - <xsl:otherwise> - <!-- We need to recurse downwards; so we need to strip off a directory element off our absolute path to feed - into the next iteration... --> - <xsl:variable name="relative_path_depth" select="string-length($self)-string-length(translate($self, '/' , ''))"/> - <xsl:variable name="relative_path_fixed"> - <xsl:for-each select="str:tokenize_plasmaroo($self, '/')[position() < (($relative_path_depth - 1)*2 + 1)]"> - <xsl:value-of select="."/> - </xsl:for-each> - </xsl:variable> - <xsl:call-template name="findNext"> - <xsl:with-param name="self" select="$relative_path_fixed"/> - </xsl:call-template> - </xsl:otherwise> - </xsl:choose> - </xsl:otherwise> - </xsl:choose> - </xsl:template> - - <xsl:template name="getLastNode"> - <!-- This function recurses forward down nodes stopping at the very last include... --> - <xsl:param name="root"/> - <xsl:param name="path"/> - <xsl:variable name="include" select="document(concat($root, $path))/guide/include[last()]/@href"/> - <xsl:choose> - <xsl:when test="$include"> - <xsl:call-template name="getLastNode"> - <xsl:with-param name="root" select="$root"/> - <xsl:with-param name="path" select="concat(substring-before($path, 'text.xml'), $include, 'text.xml')"/> - </xsl:call-template> - </xsl:when> - <xsl:otherwise> - <xsl:value-of select="$path"/> - </xsl:otherwise> - </xsl:choose> - </xsl:template> - - <xsl:template name="findPrevious"> - <xsl:choose> - <!-- To find the "previous" node: - * Go down to our parent - * See if there are any nodes before us - * If we have a valid node that is before us - * Fully recurse up the node to get the last extremity - * Otherwise list the parent --> - <xsl:when test="/guide/@root"> - <a href="#"><span class="glyphicon glyphicon-arrow-left"/>  <xsl:value-of select="/guide/chapter[1]/title"/></a> - </xsl:when> - <xsl:otherwise> - <!-- This document's path --> - <xsl:variable name="doc_self" select="concat(/guide/@self, 'text.xml')"/> - <!-- Turn the absolute path we have into a relative path so we can find ourselves in the - parent --> - <!-- FIXME: Bombproof the doc_self so it still works if it's missing a '/' on the end --> - <xsl:variable name="path_self" select="concat(str:tokenize(/guide/@self, '/')[last()], '/')"/> - <xsl:variable name="index_self" select="count(document(concat(/guide/@self, '../text.xml'))/guide/include[@href=$path_self]/preceding-sibling::*)-1"/> - <xsl:choose> - <xsl:when test="$index_self > 0"> - <!-- Relative path of the parent --> - <xsl:variable name="parentItem_path" select="document(concat(/guide/@self, '../text.xml'))/guide/@self"/> - <!-- Previous item in the parent --> - <xsl:variable name="parentItem_next" select="document(concat(/guide/@self, '../text.xml'))/guide/include[$index_self]/@href"/> - <xsl:variable name="myItem_path"> - <xsl:call-template name="getLastNode"> + </xsl:choose> +</xsl:template> + +<xsl:template name="findPrevious"> + <xsl:choose> + <!-- To find the "previous" node: + * Go down to our parent + * See if there are any nodes before us + * If we have a valid node that is before us + * Fully recurse up the node to get the last extremity + * Otherwise list the parent --> + <xsl:when test="/guide/@root"> + <a class="w-250 text-center" href="#"> + <span class="fa fa-arrow-left"/> + <span class="truncated-text d-inline-block max-w-200 ml-2"> + <xsl:value-of select="/guide/chapter[1]/title"/> + </span> + </a> + </xsl:when> + <xsl:otherwise> + <!-- Turn the absolute path we have into a relative path so we can find + ourselves in the parent --> + <xsl:variable name="path_self" select="concat(str:tokenize(/guide/@self, '/')[last()], '/')"/> + <xsl:variable name="index_self" select="count(document(concat(/guide/@self, '../text.xml'))/guide/include[@href=$path_self]/preceding-sibling::*)-1"/> + <xsl:choose> + <xsl:when test="$index_self > 0"> + <!-- Relative path of the parent --> + <xsl:variable name="parentItem_path" select="document(concat(/guide/@self, '../text.xml'))/guide/@self"/> + <!-- Previous item in the parent --> + <xsl:variable name="parentItem_next" + select="document(concat(/guide/@self, '../text.xml'))/guide/include[$index_self]/@href"/> + <xsl:variable name="myItem_path"> + <xsl:call-template name="getLastNode"> <xsl:with-param name="root" select="$parentItem_path"/> - <xsl:with-param name="path" select="concat($parentItem_next, 'text.xml')"/> - </xsl:call-template> - </xsl:variable> - <!-- Make a relative <a> link; we need an absolute reference for the XSLT processor though... --> - <a href="{concat('../', substring-before($myItem_path, 'text.xml'), 'index.html')}"><span class="glyphicon glyphicon-arrow-left"/>  <xsl:value-of select="document(concat($parentItem_path, $myItem_path))/guide/chapter[1]/title"/></a> - </xsl:when> - <xsl:otherwise> - <a href="../index.html"><span class="glyphicon glyphicon-arrow-left"/>  <xsl:value-of select="document(concat(/guide/@self, '../text.xml'))/guide/chapter[1]/title"/></a> - </xsl:otherwise> - </xsl:choose> - </xsl:otherwise> - </xsl:choose> - </xsl:template> - - <xsl:template name="printParentDocs"> - <xsl:param name="depth"/> - <xsl:choose> - <xsl:when test="$depth > 0"> - <xsl:variable name="relative_path_depth_recursion"> - <xsl:call-template name="str:repeatString"> - <xsl:with-param name="count" select="$depth"/> - <xsl:with-param name="append">../</xsl:with-param> - </xsl:call-template> - </xsl:variable> - - <li><a href="{$relative_path_depth_recursion}index.html"><xsl:value-of select="document(concat(/guide/@self, concat($relative_path_depth_recursion, 'text.xml')))/guide/chapter[1]/title"/></a></li> + <xsl:with-param name="path" select="$parentItem_next"/> + </xsl:call-template> + </xsl:variable> + <!-- Make a relative <a> link; we need an absolute reference + for the XSLT processor though... --> + <a class="w-250 text-center" href="{concat('../', $myItem_path, 'index.html')}"> + <span class="fa fa-arrow-left"/> + <span class="truncated-text d-inline-block max-w-200 ml-2"> + <xsl:value-of select="document(concat($parentItem_path, $myItem_path, 'text.xml'))/guide/chapter[1]/title"/> + </span> + </a> + </xsl:when> + <xsl:otherwise> + <a class="w-250 text-center" href="../index.html"> + <span class="fa fa-arrow-left"/> + <span class="truncated-text d-inline-block max-w-200 ml-2"> + <xsl:value-of select="document(concat(/guide/@self, '../text.xml'))/guide/chapter[1]/title"/> + </span> + </a> + </xsl:otherwise> + </xsl:choose> + </xsl:otherwise> + </xsl:choose> +</xsl:template> - <xsl:call-template name="printParentDocs"> - <xsl:with-param name="depth" select="$depth - 1"/> +<xsl:template name="printParentDocs"> + <xsl:param name="depth" select="string-length(/guide/@self) - string-length(translate(/guide/@self, '/', ''))"/> + <xsl:choose> + <xsl:when test="$depth > 0"> + <xsl:variable name="relative_path_depth_recursion"> + <xsl:call-template name="repeat-string"> + <xsl:with-param name="count" select="$depth"/> + <xsl:with-param name="append">../</xsl:with-param> </xsl:call-template> - </xsl:when> - </xsl:choose> - </xsl:template> - - <xsl:template name="findParent"> - <xsl:choose> - <xsl:when test="not(/guide/@root)"> - <a href="../index.html">↑ <xsl:value-of select="document(concat(/guide/@self, '../text.xml'))/guide/chapter[1]/title"/> ↑</a> + </xsl:variable> + <li> + <a href="{$relative_path_depth_recursion}index.html"> + <xsl:value-of select="document(concat(/guide/@self, $relative_path_depth_recursion, 'text.xml'))/guide/chapter[1]/title"/> + </a> + </li> + <xsl:call-template name="printParentDocs"> + <xsl:with-param name="depth" select="$depth - 1"/> + </xsl:call-template> </xsl:when> - <xsl:otherwise> - <a href="#">↑ <xsl:value-of select="/guide/chapter[1]/title"/> ↑</a> - </xsl:otherwise> - </xsl:choose> - </xsl:template> - - <xsl:template match="author"> - <dt><xsl:value-of select="@name"/><xsl:if test="@email != ''"> <<a href="mailto:{@email}"><xsl:value-of select="@email"/></a>></xsl:if></dt> - <dd><xsl:apply-templates/></dd> - </xsl:template> - - <xsl:template match="authors"> - <dl> - <xsl:apply-templates select="author"/> - </dl> - </xsl:template> + </xsl:choose> +</xsl:template> + +<xsl:template match="author"> + <dt> + <xsl:value-of select="@name"/> + <xsl:if test="@email != ''"> <<a href="mailto:{@email}"><xsl:value-of select="@email"/></a>></xsl:if> + </dt> + <dd><xsl:apply-templates/></dd> +</xsl:template> + +<xsl:template match="authorlist"> + <dt><xsl:value-of select="@title"/></dt> + <dd> + <xsl:for-each select="document(concat(@href, 'text.xml'))//author"> + <xsl:value-of select="@name"/> + <xsl:if test="position() != last()">, </xsl:if> + </xsl:for-each> + </dd> +</xsl:template> + +<xsl:template match="authors"> + <dl> + <xsl:apply-templates/> + </dl> +</xsl:template> + </xsl:stylesheet> + +<!-- Local Variables: --> +<!-- indent-tabs-mode: nil --> +<!-- fill-column: 120 --> +<!-- End: --> diff --git a/devmanual.css b/devmanual.css index 6f24642..83f6b14 100644 --- a/devmanual.css +++ b/devmanual.css @@ -1,180 +1,103 @@ -div.header { - border-bottom: 3px solid #333333; - background-color: #666666; - color: #eeeeee; - margin: 0em 0em 0em 0em; - padding: 0.2em; - font-size: 70%; -} - -div.navtop { - border-bottom: 1px dashed #333333; - text-align: center; -} - -div.navbottom { - border-top: 1px dashed #333333; - text-align: center; - margin-top: 1em; -} - -@media print { - div.header { - display: none; - } -} - -div.header a:link, div.header a:visited, -div.footer a:link, div.footer a:visited { - color: #eeeeee; +th { font-weight: bold; - text-decoration: none; + text-align: left; } -div.header a:hover, div.footer a:hover { - color: #eeeeee; +dt { font-weight: bold; - text-decoration: underline; } -div.footer { - text-align: center; - border-top: 3px solid #333333; - background-color: #666666; - color: #eeeeee; - margin: 0em 0em 0em 0em; - padding: 0em 0.2em; - font-size: 70%; -} - -@media print { - div.footer { - display: none; - } -} - -div.main { - padding: 1em 40px; - margin: 0em; - background-color: #eeeeee; - color: #333333; -} - -body { - background-color: #666666; - color: #eeeeee; - padding: 0em; - margin: 0em; - font-family: "Verdana", "Arial", "Helvetica", sans-serif; -} - -div.footer * img { - border-width: 0px; +dd { + margin-top: 0.2em; + margin-bottom: 0.2em; + margin-left: 2em; } -th { +div.figure, div.figure p { + text-align: center; font-weight: bold; - text-align: left; - padding: 0.3em; -} - -th, td { - padding-left: 0.3em; - padding-right: 0.3em; } -div.main a:link, div.main a:visited { - color: #000099; - text-decoration: none; +code, pre { + font-family: monospace; + tab-size: 4; + -o-tab-size: 4; + -moz-tab-size: 4; } -div.main a[href]:hover { - color: #000099; - text-decoration: underline; -} +pre span.Special { color: magenta; } +pre span.Identifier { color: blue; } +pre span.Type { color: blue; } +pre span.PreProc { color: magenta; } +pre span.Constant { color: black; } +pre span.Comment { color: red; } +pre span.Statement { color: darkred; } -div.main pre a:link, div.main pre a:visited { - color: #fff0e0; +a.permalink { + margin: 0em 0.3em; + font-size: 90%; text-decoration: none; + visibility: hidden; } -div.main pre a[href]:hover { - color: #fff0e0; - text-decoration: underline; -} - -code, tt { - color: #993333; -} - -div.main p, div.main dd { - text-align: justify; +h1:hover > a.permalink, +h2:hover > a.permalink, +h3:hover > a.permalink, +h4:hover > a.permalink { + visibility: visible; } -pre { - background-color: #1e1e27; - color: #cfbfad; - padding-top: 3px; - padding-bottom: 3px; - padding-left: 8px; - padding-right: 8px; +.truncated-text { + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; + vertical-align: top; } -div.main h1 { - text-align: center; +.w-250 { + width: 250px; } -div.main h2 { - text-align: left; - border-bottom: 1px dashed #333333; - margin-left: -30px; +.max-w-200 { + max-width: 200px; } -div.main h3 { - text-align: left; - margin-left: -30px; -} - -dt { - font-weight: bold; +/* compatible to Bootstrap 4 for future migration */ +.d-inline-block { + display: inline-block; } -dd p.first { - margin-top: 0.2em; +/* compatible to Bootstrap 4 for future migration */ +.text-center { + text-align: center; } -dd p.last { - margin-bottom: 0.2em; +/* compatible to Bootstrap 4 for future migration */ +.mr-2 { + margin-right: 8px; } -div.figure, div.figure p { - text-align: center; - font-weight: bold; +/* compatible to Bootstrap 4 for future migration */ +.ml-2 { + margin-left: 8px; } -code, pre, tt { - font-family: monospace; +/* vertically center the search bar */ +.navbar-grey .input-group { + margin-top: 3px; } -blockquote.epigraph p { - font-size: 80%; - font-style: italic; -} +/* + * .fix-links can be used to fix listgroups in text browsers + * see https://bugs.gentoo.org/show_bug.cgi?id=711286 + */ -blockquote.epigraph p.attribution { - font-style: normal; +.fix-links > li { + padding: 0px; } -td.devbook { - vertical-align: top; +.fix-links > li > a { + border: none; } -pre span.Special { color: magenta; } -pre span.Identifier { color: blue; } -pre span.Type { color: blue; } -pre span.PreProc { color: magenta; } -pre span.Constant { color: black; } -pre span.Comment { color: red; } -pre span.Statement { color: darkred; } - /* vim: set ts=4 tw=80 et : */ diff --git a/ebuild-maintenance/git/text.xml b/ebuild-maintenance/git/text.xml new file mode 100644 index 0000000..2f3fcb3 --- /dev/null +++ b/ebuild-maintenance/git/text.xml @@ -0,0 +1,317 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-maintenance/git/"> +<chapter> +<title>Git for Gentoo Developers</title> +<body> + +<p> +This guide covers git usage instructions and policies specific to Gentoo ebuild +development. It assumes that the readers possess basic git knowledge. +For a generic guide, please see the official +<uri link="https://git-scm.com/book/">git book</uri>. +</p> +</body> + +<section> +<title>Preparing a development checkout</title> + +<subsection> +<title>Cloning the gentoo.git repository</title> +<body> + +<p> +The ebuild development happens on the official git repository. You can push +your changes only through the SSH protocol. Therefore, clone the repository +using: +</p> + +<pre> +git clone git@git.gentoo.org:repo/gentoo.git +</pre> + +<p> +If you do not have SSH access to the Gentoo git service, you can use the anongit +mirror for read-only access instead: +</p> + +<pre> +git clone https://anongit.gentoo.org/git/repo/gentoo.git +</pre> + +<p> +Normally git will fetch the complete history from the start of git repository +(Aug 2015). This can require a significant amount of disk space. If you do not +need the full history, you can use the <c>--depth</c> option to create a shallow +clone, including only a subset containing the the newest commits. For example, +<c>--depth=50</c> will include the 50 newest commits. +</p> + +<p> +Please note that git version 1.9 or newer is required to push when using +a shallow clone. +</p> + +</body> +</subsection> + +<subsection> +<title>Configuration specific to the Gentoo repository</title> +<body> + +<p> +To ensure that the Gentoo policies are followed, you should set the following +configuration variables: +</p> + +<pre> +git config --local user.name "${YOUR_FULL_NAME}" +# use your @gentoo.org address even if you have a different default +git config --local user.email "${YOUR_NICKNAME}@gentoo.org" + +# enable commit and push signing +git config --local user.signingkey "0x${LONG_OPENPGP_KEY_ID}" +git config --local commit.gpgsign 1 +git config --local push.gpgsign 1 + +# prevent implicit merges on 'git pull' +git config --local pull.ff only +</pre> + +</body> +</subsection> + +<subsection> +<title>Grafting converted CVS history into the clone</title> +<body> + +<p> +To include the converted CVS history in the git repository, you can +graft it into the repository: +</p> + +<pre> +git remote add history https://anongit.gentoo.org/git/archive/repo/gentoo-2.git +git fetch history +git replace --graft 56bd759df1d0c750a065b8c845e93d5dfa6b549d cvs-final-2015-08-08 +</pre> + +<p> +Once this is done, git commands such as <c>git log</c> will include +the historical commits after the initial git commit. +</p> + +</body> +</subsection> +</section> + +<section> +<title>Committing to gentoo.git</title> + +<subsection> +<title>Committing and verifying commits</title> +<body> + +<p> +The recommended way of committing to the Gentoo repository is to use <c>pkgdev +commit</c> (then <c>pkgdev push</c>). It automatically performs the necessary +QA checks on the package being committed and has other features helping with +the Gentoo workflow. +</p> + +<p> +For any other use case, <c>git commit</c> and other git commands need to be +used. The valid uses of git include: +</p> + +<ul> + <li> + creating commits spanning multiple packages and/or multiple areas of the + Gentoo repository (eclasses, licenses, profiles…), + </li> + <li> + amending a commit created via <c>pkgdev commit</c> with additional files + or fixups, + </li> + <li> + combining multiple commits created via <c>pkgdev commit</c> using + <c>git rebase</c>. + </li> +</ul> + +<p> +Whenever <c>pkgdev</c> is not used to commit, you need to manually verify all +packages affected by the commit using <c>pkgcheck scan --commits</c>. Also, +when using <c>git</c> manually, you must perform a manual sign-off to the +<uri link="::general-concepts/copyright-policy/#Certificate of origin"/> using +the <c>-s </c> or <c>--signoff</c> option with your git commit commands. Make +sure you have read and understand the actual certificate. +</p> + +</body> +</subsection> + +<subsection> +<title>Atomic commits</title> +<body> + +<p> +Whenever possible, use atomic commits. Try to split your changes into logical +commits, abiding by the following three rules as much as possible: +</p> + +<ol> + <li> + Do not include multiple irrelevant changes in a single commit. However, + make sure not to split relevant changes unnecessarily. For example, if a + version bump requires changes in the ebuild, it is correct to perform them + in a single commit. However, if you are fixing an additional bug that has + been present in the previous version, the fix belongs in a separate commit. + </li> + <li> + Split commits at logical unit boundaries. When updating multiple packages, + preferably use a single commit for each package. Avoid combining changes + to ebuilds, eclasses, licenses, profiles etc. in a single commit. However, + do not split relevant or interdependent changes within a single package. + </li> + <li> + Avoid creating commits introducing a temporary breakage. Unless impossible, + add packages in dependency install order. Add licenses before the packages + needing them. Commit <c>package.mask</c> and other profile changes before + ebuilds relying on them. Usually it is also acceptable to include those + changes along with the commit adding the package. + </li> +</ol> + +<p> +Please note that revision bumps count as side effects of the changes requiring +them and do not belong in separate commits. When doing multiple irrelevant +changes that require a revision bump, it is only necessary to bump the revision +in the first commit in the series introduced by a single push. +</p> + +</body> +</subsection> + +<subsection> +<title>Git Commit Message Format</title> +<body> + +<p> +It is important to format the commit messages properly so that they +communicate the changes to the reader in a clear and concise +way. Additionally, consistency in message format allows for easier +parsing by external tools. The first line of the commit message should +contain a brief summary of the changes, followed by an empty new +line. From the third line onward should be a detailed, multiline +explanation of the changes introduced by the commit. At the very end, +auxiliary information such as the bugs related to the commit, +contributors, and reviewers should be listed using RFC822/git style +tags. The sign-off agreement will be added there as well when applied +with the commit action. The length of the lines in the message should +be 70-75 characters at maximum. +</p> + +<p> +The summary line should start with referencing what is affected by the +change followed by a colon ':' character. Use the rules in the +following list to determine the proper format based on what has +changed, substituting the package, category and eclass names +appropriately: +</p> + +<ul> + <li> + <c>${CATEGORY}/${PN}:</c> Single Package (Note that <c>pkgdev commit</c> + will automatically insert this for you) + </li> + <li><c>${CATEGORY}:</c> Package Category</li> + <li><c>profiles:</c> Profile Directory</li> + <li><c>${ECLASS}.eclass:</c> Eclass Directotry</li> + <li><c>licenses:</c> Licenses Directory</li> + <li><c>metadata:</c> Metadata Directory</li> +</ul> + +<p> +For packages where <c>${CATEGORY}/${PN}:</c> is long, the line length +limit can be exceeded, if absolutely necessary, to ensure a more +useful summary line. If a commit affects multiple directories, prepend +the message with which reflects the intention of the change best. If +there are any bugs on Gentoo Bugzilla associated with the commit, the id +of the bug can be appended to the summary line using the format +<c>#nnnnnn</c>. If you are modifying keywords, clearly state what +keywords are added/removed. +</p> + +<warning> +By default, lines starting with <c>#</c> are considered to be comments +by git and not included in the commit message. Make sure that a new +line does not start with <c>#nnnnnn</c>. Optionally, git can be +configured to use a different character for comments by changing the +<c>commentchar</c> option. +</warning> + +<p> +For non-trivial commits, the message should contain a detailed +explanation of what the commit intends to change, why it is required, +and how it is accomplished, along with any other supplementary +information. +</p> + +<p> +Finally the commit message should list auxiliary information such as +people who are involved in authoring, suggesting, reviewing and +testing the changes, and revelant bugs. Use RFC822/git style tags as +explained in the +<uri link="https://kernel.org/doc/html/latest/process/submitting-patches.html"> +Linux Kernel patch guideline</uri>. Additionally, the following tags +are optionally used in Gentoo: +</p> + +<ul> + <li> + <c>Bug:</c> Use this to reference bugs <e>without</e> closing them. + The value is a URL to the bug. If multiple bugs need to be referenced, + each one should be listed in a separate <c>Bug</c> tag. If a bug on + Gentoo Bugzilla, or an issue or a pull request on GitHub is referenced, + a reference to the commit will be added automatically. + </li> + <li> + <c>Closes:</c> Use this to reference bugs and close them automatically. + Alike <c>Bug:</c>, the value is a single URL to the bug, and multiple tags + can be used to close multiple bugs. If a bug on Gentoo Bugzilla, or an + issue or a pull request on a GitHub repository mirrored by Gentoo is + referenced, it will be closed (as fixed) automatically with reference + to the commit. + </li> +</ul> + +<p> +When committing <uri link="::ebuild-writing/user-submitted/">user +contributions</uri>, make sure to credit them in your commit message +with the user's full name and email address. Be aware and respectful +of their privacy: some users prefer to be only known by a nickname. +Take advantage of tags such as <c>Suggested-by:</c> or +<c>Reported-by:</c> when entering such information to the commit +message. +</p> + +<p> +An example commit message is shown below: +</p> + +<pre> +app-misc/foo: version bump to 0.5 + +This also adds a new USE flag 'bar' which controls the +new bar functionality introduced with this version. + +Bug: https://bugs.gentoo.org/00000 +Closes: https://bugs.gentoo.org/00001 +Signed-off-by: Alice Bar <a.bar@example.org> +</pre> + +</body> +</subsection> +</section> +</chapter> +</guide> diff --git a/ebuild-maintenance/new-ebuild/text.xml b/ebuild-maintenance/new-ebuild/text.xml new file mode 100644 index 0000000..10793e0 --- /dev/null +++ b/ebuild-maintenance/new-ebuild/text.xml @@ -0,0 +1,133 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-maintenance/new-ebuild/"> +<chapter> +<title>Adding a New Ebuild</title> + +<section> +<title>What (not) to put in the Gentoo repository</title> +<body> + +<p> +Before writing a new ebuild, check <uri link="https://bugs.gentoo.org/"> +bugs.gentoo.org</uri> to see if an ebuild has already been written for +the package, but has not yet been added to the Gentoo repository. Go to +<uri link="https://bugs.gentoo.org/">bugs.gentoo.org</uri>, choose query and +select Advanced Search; as product select <e>Gentoo Linux</e>, as component +select <e>New packages</e>. In the search field put the name of the ebuild and +as status and resolution select all possible fields, then submit the query. +For you lazy people, here is a +<uri link="https://bugs.gentoo.org/query.cgi?format=advanced&product=Gentoo%20Linux&component=New%20packages"> +Bugzilla advanced search</uri> link. +</p> + +<p> +The Gentoo repository should only be used for storing <c>.ebuild</c> files, +as well as any small companion files, such as patches or sample configuration +files. These files should have a size of at most 20 KiB and must be placed +in the <c>mycat/mypkg/files</c> directory, which can be referenced as +<c>${FILESDIR}</c> from within ebuilds. +</p> + +<p> +Larger patches should be placed in your developer space on <c>dev.gentoo.org</c> +instead of the tree, in order to minimize the repository size. +Non-developers such as proxied maintainers can host patches at some stable +location of their own <d/> there is no security issue here as the Manifest +will record patch checksums at the time of commit. +</p> + +<p> +The files in the repository should be uncompressed plain text files, i.e., +no binaries. This will allow the version control system to merge changes and +correctly inform developers of conflicts. +</p> + +<p> +Remember, the packages that you commit must be <e>ready</e> <e>out of the +box</e> for end users when committed as stable. Make sure that you have a good +set of default settings that will satisfy the majority of systems and +users that will use your package. If your package is broken, and you are +not sure how to get it to work, check some other distributions that have +done their own versions of the package. You can check +<uri link="https://www.debian.org/distrib/packages">Debian</uri> or +<uri link="https://src.fedoraproject.org/projects/rpms/*">Fedora</uri> for some +examples. +</p> + +<p> +When committing to git, all developers should use <c>pkgdev commit</c> with +<c>pkgdev push</c> instead of <c>git commit</c> to submit their ebuilds. +Before committing, please run <c>pkgcheck scan --commits</c> to make sure you +didn't forget something. +</p> + +</body> +</section> + +<section> +<title>Initial Architecture Keywords</title> +<body> + +<p> +When adding a new ebuild, you should only include <c>KEYWORDS</c> for +architectures on which you have actually tested the ebuild, confirming +that it works as it should and that <c>USE</c> flags are properly +honoured in the resulting package which would be installed. If +possible, you should give the actual library or application thorough +testing as well, since you would be responsible for any breakages for +your architecture(s). Minimal testing such as checking that the +application starts up without any errors should always be performed. +</p> + +<p> +If you are adding a user-submitted ebuild, do not assume that the +submitter has done testing on various architectures: often, <c>KEYWORDS</c> +are cloned across packages or generated from documentation in the +source packages, which does not signify that the package does indeed +work on those architectures. +</p> + +</body> +</section> + +<section> +<title>The files Directory</title> +<body> + +<p> +As noted earlier, under each package subdirectory is +a <c>files/</c> directory. Any patches, configuration files, or +other ancillary files your package might require should be added to +this directory; any files bigger than 20KB-or-so should go to the +mirrors to lower the amount of (unneeded) files our users have to +download. You may want to consider naming patches you create yourself +just to get your package to build with a version-specific name, such +as <c>mypkg-1.0-gentoo.patch</c>, or more +simply, <c>1.0-gentoo.patch</c>. Also note that the +<c>gentoo</c> extension informs people that this patch was created +by us, the Gentoo Linux developers, rather than having been grabbed from a +mailing list or somewhere else. Again, you should not compress these +patches. +</p> + +<p> +Consider prefixing or suffixing (such as <c>mypkg-1.0</c>) every file +you put into the <c>files/</c> directory, so that the files used for +each individual version on an ebuild are distinguishable from one another, and +so that the changes between different revisions are visible. This is generally +a really good idea :). You may want to use a different suffix if you wish to +convey more meaning with the patch name. +</p> + +<p> +If you have many files that should go into the <c>files/</c> directory, +consider creating subdirectories such as <c>files/1.0/</c> and putting the +relevant files in the appropriate subdirectory. If you use this method, +you do not need to add version information to the names of the files, +which is often more convenient. +</p> + +</body> +</section> +</chapter> +</guide> diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml new file mode 100644 index 0000000..9c07db5 --- /dev/null +++ b/ebuild-maintenance/package-moves/text.xml @@ -0,0 +1,165 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-maintenance/package-moves/"> +<chapter> +<title>Package and Slot Moves</title> +<body> + +<p> +This chapter describes the use of package and slot moves. The package update +mechanism is a powerful tool, and needs to be used with caution. In particular, +the following must be noted: +</p> + +<ol> + <li> + <uri link="::profiles/updates/">Updates</uri> are <e>not one-shot</e> + operations and they are not stateful. All updates can be reapplied multiple + times to the same system, and all old updates are applied to fresh Gentoo + installations. + </li> + <li> + Once an update entry is created, the old package name (or slot) cannot be + reused for another package. Attempting to reuse it will cause updates to + apply again, to the reused name. This also means that while a package can + be moved back to its previous name, all the names historically used for + a package are reserved to it alone. + </li> + <li> + Updates can only perform one-to-one moves. They cannot be used to merge + packages. Attempting to move two or more packages into a single name may + cause serious problems for users. + </li> +</ol> + +</body> + +<section> +<title>Moving or renaming a package</title> +<body> + +<p> +Moving or renaming a package (sometimes called a "pkgmove" or just "move") +requires several operations. Firstly, verify that the ebuilds will continue to +work correctly after the move. If the category changes, you must verify all +<c>${CATEGORY}</c> uses. If the package name changes, you must verify +<c>${PN}</c>, <c>${P}</c>, etc. Whenever the old value is necessary, +substitute the variable reference with the verbatim text, so that it won't get +affected by the move. Commit the changes separately before moving +the package. +</p> + +<p> +Afterwards, move the package files using <c>git mv</c>. Add the move entry +to <c>profiles/updates/</c> in the following format: +</p> + +<pre> +move old-category/old-name new-category/new-name +</pre> + +<p> +Following the update entry, find all references to the old package name +and update them. These include: +</p> + +<ul> + <li> + <uri link="::general-concepts/dependencies/">dependencies</uri>, + <c>optfeature.eclass</c> uses, <c>has_version</c> and <c>best_version</c> + uses in other ebuilds and eclasses + </li> + <li> + all <c>profiles/</c> tree entries (e.g. <c>profiles/package.mask</c>) + </li> + <li> + <c>restrict</c> entries in package <c>metadata.xml</c> files, as well + as <c><pkg/></c> tags + </li> + <li> + news item <c>Display-If-Installed</c> + </li> + <li> + open bug summaries + </li> + <li> + wiki pages + </li> +</ul> + +<p> +Preferably, combine all those changes into a single commit to ensure atomicity +during the update. +</p> + +</body> +</section> + +<section> +<title>Changing ebuild's SLOT</title> +<body> + +<p> +The process for changing the ebuild's <c>SLOT</c> (a "slotmove") is very similar to the +previous process. Besides changing the <c>SLOT</c> in the ebuild file, you +also need to create a new entry in <c>profiles/updates/</c> in +the Gentoo repository in the following format: +</p> + +<pre> +slotmove app-text/gtkspell 0 2 +</pre> + +<p> +Make sure that you have fixed all the reverse dependencies and that +you have updated every file in <c>profiles/</c> directory that +happens to contain an entry which may be affected by your change. +</p> + +</body> +</section> + +<section> +<title>Updating prior update entries when moving the package again</title> +<body> + +<p> +When the same package is moved again, the previous update entries should +be updated appropriately. This is meant to make the situation more transparent +to users reading update entries and to ensure that the process is handled +efficiently even if the package manager does not implement updates in a robust +way. This involves the following steps: +</p> + +<ol> + <li> + The previous package moves for the package in question must be updated + to reference the final name. That is, rather than the chain A → B → C, + we want to have two update entries: A → C, and B → C. + </li> + + <li> + If the package is being moved to a name that it used before, the original + move entry must be removed. That is, rather than the chain A → B → A, + we want to have the reverse entry: B → A. If the package manager did not + move A → B before, we don't want it to touch the package at all. + </li> + + <li> + As a combination of the two aforementioned steps, a chain of A → B → C → A + would be replaced by two moves: B → A, and C → A. + </li> + + <li> + If the package was slot-moved before, the slot moves should be updated + to use the final package name, and moved after the final package move. + That is, rather than the chain: A:S<sub>1</sub> → A:S<sub>2</sub>, A → B; + we prefer to have the chain: A → B, B:S<sub>1</sub> → B:S<sub>2</sub>. + All package and slot move entries must reside in the same file then, to + guarantee sequential processing. + </li> +</ol> + +</body> +</section> +</chapter> +</guide> diff --git a/ebuild-maintenance/removal/text.xml b/ebuild-maintenance/removal/text.xml new file mode 100644 index 0000000..bdeae71 --- /dev/null +++ b/ebuild-maintenance/removal/text.xml @@ -0,0 +1,130 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-maintenance/removal/"> +<chapter> +<title>Removing Ebuilds and Packages</title> + +<section> +<title>Removing ebuilds</title> +<body> + +<p> +When removing an ebuild make sure that no dependencies in Portage are broken +due to the removal <d/> additionally, your git commit message should explain +clearly why the ebuild is being removed from the git repository. +</p> + +<p> +If you need to remove ebuilds, make sure you do not accidentally remove +the newest/only stable ebuild for any architecture. If you would like to +get a newer version marked stable, then please file a bug or ask on IRC. +</p> + +<p> +You should also not cause an unnecessary downgrade for any <c>~arch</c> when +removing ebuilds <d/> instead, it is best to get the newest version marked +<c>~arch</c> first and then remove redundant versions of the ebuild. +</p> + +</body> +</section> + +<section> +<title>Removing a package</title> +<body> + +<p> +When removing packages follow these steps: +</p> + +<ol> + <li> + Make sure that no dependencies in the Gentoo repository are broken due to + the removal + </li> + <li>Send last rites to gentoo-dev-announce and gentoo-dev</li> + <li>Mask the package</li> + <li>Wait 30 days (or more)</li> + <li>Remove from the git tree unless the reason for removal has been fixed</li> + <li> + Remove any references to the package from other ebuilds, e.g., + use-conditional dependencies. Blockers are the only exception to this. + </li> + <li>Remove package.mask and any package.use.mask entries</li> + <li> + Remove the <c><pkg></c> tags referencing this package in the + <uri link="::ebuild-writing/misc-files/metadata/">metadata.xml</uri> + files of other packages. + </li> + <li>Close open bugs as WONTFIX</li> +</ol> + +<p> +Here is a list of commands that will delete <c>dev-util/pmk</c> +from the tree: +</p> + +<pre> +# cd dev-qt +# git rm -rf qtphonon +# git commit --signoff --gpg-sign +</pre> + +<p> +An example commit message is shown below: +</p> + +<pre> +commit b97eb6d43f45dfd5b739638928db22d3f3392685 +Author: Michael Palimaka <kensington@gentoo.org> +Date: Tue Oct 3 21:43:03 2017 +1100 + + dev-qt/qtphonon: remove last rited package + + Closes: https://bugs.gentoo.org/629144 +</pre> + +</body> +</section> + +<section> +<title>Removing a virtual package</title> +<body> + +<p> +Virtual packages are generally removed when they have no more than one +provider left. The removal is preceded by updating the remaining ebuilds +not to use the virtual. Since virtuals do not install any files, there +is little value in proactively forcing them to be uninstalled from user +systems or unnecessarily informing the user about the fact. Therefore, +an alternative removal process is recommended. +</p> + +<p> +In order to remove a virtual package, follow the following procedure: +</p> + +<ol> + <li> + If the virtual is being removed along with any of its providers, + include the virtual in the last-rites mail. However, please + do not include it in the <c>package.mask</c> entry as users do not need + to be forced to proactively unmerge it. Instead, add it + to <c>package.deprecated</c> to warn developers not to depend on it. + Wait the time appropriate for the last rites. + </li> + <li> + Update all ebuilds not to reference the virtual, following normal + <uri link="::general-concepts/ebuild-revisions/"/> policy + </li> + <li> + Remove the package directly + </li> + <li> + Perform the post-removal cleanup, as with regular packages + </li> +</ol> + +</body> +</section> +</chapter> +</guide> diff --git a/ebuild-maintenance/text.xml b/ebuild-maintenance/text.xml new file mode 100644 index 0000000..2a7ecff --- /dev/null +++ b/ebuild-maintenance/text.xml @@ -0,0 +1,27 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-maintenance/"> +<chapter> +<title>Ebuild Maintenance</title> +<body> + +<p> +This section aims to explain common everyday ebuild maintenance routines, +as well as other rarer maintenance routines which developers may not be +familiar with. +</p> + +</body> + +<section> +<title>Contents</title> +<body> +<contentsTree/> +</body> +</section> +</chapter> + +<include href="new-ebuild/"/> +<include href="git/"/> +<include href="package-moves/"/> +<include href="removal/"/> +</guide> diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index ff906fd..41f6d35 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/common-mistakes/"> <chapter> <title>Common Mistakes</title> @@ -12,14 +12,29 @@ writing ebuilds. <section> <title>Common Ebuild Writing Mistakes</title> + +<subsection> +<title>Unguarded external calls</title> <body> +<p> +Calls to external tools should be guarded with <c>|| die</c> (or use +<c>assert</c>) in almost all cases to allow failure to be detected. +See <uri link="::ebuild-writing/error-handling/"/>. +</p> + +</body> +</subsection> + <subsection> <title>Invalid use of <c>static</c> use-flag</title> <body> +<p> The <c>static</c> use-flag should only be used to make a binary use static linking instead of dynamic linking. It should not be used to make a library -install static libraries. Instead, the <c>static-libs</c> use-flag is used for this. +install static libraries. Instead, the <c>static-libs</c> use-flag is used for +this. +</p> </body> </subsection> @@ -28,13 +43,16 @@ install static libraries. Instead, the <c>static-libs</c> use-flag is used for t <body> <p> The usage of <c>ROOT</c> is only designed to influence the way the package is -installed (ie. into <c>ROOT</c>) - building and compiling should not depend on -<c>ROOT</c>. As a consequence of this the usage of <c>ROOT</c> in <c>src_*</c> -functions is not allowed. +installed (ie. into <c>ROOT</c>) <d/> building and compiling should not depend +on <c>ROOT</c>. As a consequence of this, the usage of <c>ROOT</c> in +<c>src_*</c> functions is not allowed. <c>pkgcheck</c> can now detect some +such cases via its <c>MisplacedVariable</c> check. +See <uri link="https://bugs.gentoo.org/775191">bug 775191</uri> for more +information. </p> <p> -See also <uri link="::ebuild-writing/variables#ROOT"/>. +See also <uri link="::ebuild-writing/variables/#ROOT"/>. </p> </body> </subsection> @@ -43,16 +61,20 @@ See also <uri link="::ebuild-writing/variables#ROOT"/>. <title>Referencing the full path to documentation files that could be compressed</title> <body> +<p> When printing out to the users where to find files like INSTALL, do not specify the full path since <c>PORTAGE_COMPRESS</c> comes into play. The file could be compressed with gzip, bzip2, or some other random compression tool. So, instead of doing this: +</p> <codesample lang="ebuild"> elog "They are listed in /usr/share/doc/${PF}/INSTALL.gz" </codesample> +<p> Do something like: +</p> <codesample lang="ebuild"> elog "They are listed in the INSTALL file in /usr/share/doc/${PF}" @@ -63,82 +85,133 @@ elog "They are listed in the INSTALL file in /usr/share/doc/${PF}" <subsection> <title>Build log not verbose</title> <body> +<p> When writing ebuilds, you should always check the build log, because the build system might ignore CC/CXX/LD/CFLAGS/LDFLAGS and such or add undesired flags by default. In order to analyze this and have complete information, in case someone reports a bug for your package, the <b>build log must always be verbose.</b> -<p> -There are several ways to fix non-verbose build logs depending on the build system: </p> <p> -For <c>cmake</c> based build systems it should be sufficient that the ebuild calls -cmake-utils_src_compile which picks up the cmake-utils.eclass variable 'CMAKE_VERBOSE=1' -by default. If you call emake directly for whatever reason, you can do 'emake VERBOSE=1' -(note that cmake-utils_src_compile takes arguments as well which are passed to make). +There are several ways to fix non-verbose build logs depending on the build system: </p> -<p> -For <c>autotools</c> based build systems you can pass '--disable-silent-rules' to econf, -or use EAPI 5 where that argument is passed automatically. 'emake V=1' should also work. -</p> +<ul> + <li> + For <c>cmake</c>-based build systems, it should be sufficient that the + ebuild calls cmake_src_compile which picks up the cmake.eclass variable + <c>CMAKE_VERBOSE=1</c> by default. If you call emake directly for whatever + reason, you can do <c>emake VERBOSE=1</c> (note that 'cmake_src_compile' + takes arguments as well which are passed to make). + </li> + <li> + For <c>autotools</c> based build systems, <c>econf</c> automatically + passes '--disable-silent-rules' to <c>./configure</c>. If necessary, + <c>emake V=1</c> should also work. Note that <c>V=1</c> is not a universal + parameter so may not always work. + </li> + <li> + For custom Makefiles, you often have to write a patch. Try to get + upstream to include an option like 'V=1' to enable full verbosity. + </li> + <li> + Note that when building Go manually outside of the eclass, you + will need GOFLAGS="-x". + </li> +</ul> -<p> -For custom Makefiles you often have to write a patch. Try to get upstream to include an -option like 'V=1' to enable full verbosity. -</p> <note>In case you encounter an affected package which uses a build system not -controllable by portage or eclasses you should file a bug (preferably with a patch) -and make it block the tracker bug #429308. Solutions above ebuild level are -preferred.</note> +controllable by Portage or eclasses, you should file a bug (preferably with +a patch) and make it block the tracker +<uri link="https://bugs.gentoo.org/429308">bug 429308</uri>. Solutions above +ebuild level are preferred.</note> + </body> </subsection> <subsection> <title>-Werror compiler flag not removed</title> <body> -"-Werror" is a flag which turns all warnings into errors and thus will abort compiling if any warning is encountered. +<p> +"-Werror" is a flag which turns all warnings into errors and thus will abort +compiling if any warning is encountered. +See <uri link="https://bugs.gentoo.org/260867">bug 260867</uri> for more +information and real-life examples/fixes in the Gentoo tree. +</p> -<p><b>Rationale</b><p /> -This flag is not recommended for releases and should always be disabled when encountered in build-logs, because there are numerous cases where this breaks without purpose, e.g.: +<p><b>Rationale</b></p> +<p> +This flag is not recommended for releases and should always be disabled when +encountered in build logs, because there are numerous cases where this breaks +without purpose, e.g.: +</p> <ul> <li> - new warnings on version bumps of GCC/GLIBC the developer was not aware of at the point of coding + new warnings on version bumps of GCC/glibc of which the developer was not + aware at the point of coding </li> <li> some autoconf checks will fail badly </li> <li> - libraries adding deprecated API warnings although that API is still working/supported + libraries adding deprecated API warnings although that API is still + working/supported </li> <li> - on less known architectures we may get different/more warnings than on common ones + on less known architectures we may get different/more warnings than on + common ones </li> <li> - random breakage depending on what distro/architecture/library version/kernel/userland the developer was testing "-Werror" on + random breakage depending on what distro/architecture/library + version/kernel/userland the developer was testing "-Werror" on </li> </ul> -Turning off "-Werror" we will still see the warnings, but there is no reason that they cause compile failure. Also note that portage already emits QA notices about gcc warnings that can cause runtime breakage. +<p> +By turning off "-Werror", we will still see the warnings, but there is no reason +that they cause compile failure. Note that Portage already emits QA +notices about GCC warnings that can cause runtime breakage. </p> -<p><b>How to fix</b><p /> +<p><b>How to fix</b></p> +<p> To fix the affected build system you should try the following methods: +</p> <ul> <li> - remove the compiler flag from the build system, <e>e.g. Makefile.am or configure.ac</e> or even provide a switch (for autotools based build systems that could be "--disable-werror", which is good for sending a patch upstream) + remove the compiler flag from the build system, <e>e.g. Makefile.am or + configure.ac</e> or even provide a switch (for autotools based build + systems that could be "--disable-werror", which is good for sending a patch + upstream) </li> <li> - use <e>append-flags -Wno-error</e> (needs flag-o-matic.eclass); for this to work the environment flags have to be respected and placed after build system flags; this method is not preferred as it will disable all "-Werror=specific-warning" flags as well, see next section + use <e>append-flags -Wno-error</e> (needs flag-o-matic.eclass); for this + to work the environment flags have to be respected and placed after build + system flags; this method is not preferred as it will disable all + "-Werror=specific-warning" flags as well, see next section </li> </ul> +<p> Always check that it's really gone in the build log. </p> -<p><b>Specific -Werror=... flags</b><p /> -GCC can turn any specific warning into an error. A specific -Werror flag would be "-Werror=implicit-function-declaration" for example and will only affect warnings about implicit function declarations. It's mostly safe to leave these untouched, cause they are pinned to this issue and should not cause random build time breakage. Also, we can expect that upstream did this on purpose to avoid known runtime errors and not just for testing their builds. However you should check the specified warnings yourself or ask other developers if unsure. +<p><b>Specific -Werror=... flags</b></p> +<p> +The compiler (e.g. GCC) can turn any specific warning into an error. A +specific -Werror flag would be "-Werror=implicit-function-declaration" for +example and will only affect warnings about implicit function declarations. It's +mostly safe to leave these untouched, because they are pinned to this issue and +should not cause random build-time breakage. Also, we can expect that upstream +did this on purpose to avoid known runtime errors and not just for testing their +builds. However, you should check the specified warnings yourself or ask other +developers if unsure. </p> -<p><b>Exceptions</b><p /> -Removing "-Werror" from configure.ac can cause breakage in very rare cases where the configure phase relies on the exit code. See <uri link="http://sourceforge.net/tracker/?func=detail&aid=2959749&group_id=204462&atid=989708">app-emulation/open-vm-tools bug</uri>. But even then we remove it from the resulting Makefile. +<p><b>Exceptions</b></p> +<p> +Removing "-Werror" from configure.ac can cause breakage in very rare +cases where the configure phase relies on the exit code. See +<uri link="https://sourceforge.net/p/open-vm-tools/tracker/81/"> +app-emulation/open-vm-tools bug</uri>. But even then we remove it from +the resulting Makefile. </p> </body> </subsection> @@ -148,30 +221,21 @@ Removing "-Werror" from configure.ac can cause breakage in very rare cases where <body> <p> -When you submit your ebuilds, the header should be <e>exactly</e> the same as -the one in <path>/usr/portage/skel.ebuild</path>. Most importantly, do not -modify it in any way and make sure that the <c>$Header: $</c> line is -intact. +When you submit your ebuilds, the header must be <e>exactly</e> the same as +the one in +<uri link="https://gitweb.gentoo.org/repo/gentoo.git/tree/skel.ebuild"> +skel.ebuild</uri>. </p> <p> -The first three lines <e>must</e> look like this: +The first two lines <e>must</e> look like this: </p> -<pre caption="Valid Header"> -# Copyright 1999-2004 Gentoo Foundation +<pre> +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ </pre> -<p> -Only if you are submitting a patched or version bumped ebuild, should you not -need to modify the <c>$Header: $</c> line. But the line must be present. -When we check the ebuild into CVS, it will modify that header with the -appropriate version and date information. So there is no need for you to -manually modify it. -</p> - </body> </subsection> <subsection> @@ -180,7 +244,7 @@ manually modify it. <p> You should never redefine those variables. Always use MY_P, MY_PN, MY_PV, -P0, etc. See other ebuilds that do it in portage for more information. Most +P0, etc. See other ebuilds that do it in Portage for more information. Most ebuilds use bash "Parameter Expansion". Please read the man page for bash to understand how "Parameter Expansion" works. </p> @@ -203,9 +267,9 @@ number is not consistent with the tarball/source, then use MY_P. An example dev-python/pyopenal fetches a tarball called PyOpenAL, so we redefine it like: </p> -<pre caption="Example versioning redefinition"> +<pre> MY_P=${P/pyopenal/PyOpenAL} -SRC_URI="http://oomadness.tuxfamily.org/downloads/${MY_P}.tar.gz" +SRC_URI="http://download.gna.org/pyopenal/${MY_P}.tar.gz" S=${WORKDIR}/${MY_P} </pre> @@ -223,23 +287,23 @@ part. <ul> <li> - <e>Always include the CATEGORY.</e><br /> + <e>Always include the CATEGORY.</e> For example, use <c>>=x11-libs/gtk+-2</c> and not <c>>=gtk+-2</c>. </li> <li> - <e>Do not put an asterisk (*) for >= dependencies.</e><br /> + <e>Do not put an asterisk (*) for >= dependencies.</e> For example, it should be <c>>=x11-libs/gtk+-2</c> rather than <c>>=x11-libs/gtk+-2*</c>. </li> <li><e>GTK specific. Always use =x11-libs/gtk+-1.2* for GTK+1 apps.</e></li> <li> - <e>Never depend on a meta package.</e><br /> + <e>Never depend on a meta package.</e> So don't depend on gnome-base/gnome, always depend on the specific libraries like libgnome. </li> <li> - <e>One dependency per line.</e><br /> - Don't put multiple dependency on the same line. It makes it ugly to read + <e>One dependency per line.</e> + Don't put multiple dependency on the same line. It makes it ugly to read and hard to follow. </li> </ul> @@ -250,6 +314,11 @@ part. <title>DEPEND is incomplete</title> <body> +<note> +The tips in this section apply to all dependency classes, not just +<c>DEPEND</c>. +</note> + <p> This is another very common error. The ebuild submitter submits an ebuild that "just works" without checking if the dependencies are correct. Here are @@ -258,32 +327,32 @@ some tips on how to find the correct dependencies. <ul> <li> - <e>Look in configure.in or configure.ac</e><br /> + <e>Look in configure.in or configure.ac.</e> Look for checks for packages in here. Things to look out for are pkg-config checks or AM_* functions that check for a specific version. </li> <li> - <e>Look at included .spec files</e><br /> + <e>Look at included .spec files.</e> A good indication of dependencies is to look at the included .spec files for relevant deps. However, do not trust them to be the definitive complete - list of dependencies + list of dependencies. </li> <li> - <e>Look at the application/library website</e><br /> + <e>Look at the application/library website.</e> Check the application website for possible dependencies that they suggest are needed. </li> <li> - <e>Read the README and INSTALL for the package</e><br /> + <e>Read the README and INSTALL for the package.</e> They usually also contain useful information about building and installing packages. </li> <li> <e>Remember non-binary dependencies such as pkg-config, doc generation - programs, etc.</e><br /> + programs, etc.</e> Usually the build process requires some dependencies such as intltool, libtool, pkg-config, doxygen, scrollkeeper, gtk-doc, etc. Make sure those - are clearly stated. + are clearly stated, usually in <c>BDEPEND</c>. </li> </ul> @@ -295,17 +364,17 @@ some tips on how to find the correct dependencies. <p> Another common mistake users make when submitting ebuilds is supplying an -invalid license. For example, <c>GPL</c> is not a valid license. You need to -specify <c>GPL-1</c> or <c>GPL-2</c>. Same with <c>LGPL</c>. Make sure the -license you use in the <c>LICENSE</c> field is something that exists in -<path>/usr/portage/licenses</path>. As a tip, check the <path>COPYING</path> +invalid license. For example, <c>GPL</c> is not a valid license. You need to +specify <c>GPL-1</c> or <c>GPL-2</c>. Same with <c>LGPL</c>. Make sure the +license you use in the <c>LICENSE</c> field is something that exists in +the <c>licenses</c> directory. As a tip, check the <c>COPYING</c> in a source tarball for the license. If a package does not specify it uses <c>GPL-1</c> or <c>GPL-2</c>, it is very likely it uses <c>GPL-2</c>. </p> <p> If the license for the package you submit is unique and not in -<path>/usr/portage/licenses/</path>, then you must submit the new license in a +<c>licenses/</c>, then you must submit the new license in a separate file. </p> @@ -325,6 +394,20 @@ Make sure when you bump a version, the stable KEYWORDS are all marked as </body> </subsection> <subsection> +<title>Unused flags and eclass inherits</title> +<body> + +<p> +Sometimes obsolete USE flags remain in IUSE despite having no function, e.g. +a dependency may have become mandatory but the USE flag remains in IUSE and +*DEPEND. Similarly, eclasses often become redundant due to changes in the +ebuild, or new EAPIs, e.g. <c>eutils.eclass</c> should be obsolete in modern +EAPIs. Remember to prune these. +</p> + +</body> +</subsection> +<subsection> <title>SLOT missing</title> <body> @@ -333,7 +416,7 @@ Make sure you have the SLOT variable in the ebuild. If you don't plan to use it, don't remove it. Put in: </p> -<pre caption="Default SLOT variable"> +<pre> SLOT="0" </pre> @@ -344,10 +427,16 @@ SLOT="0" <body> <p> -Please check if the HOMEPAGE variable is right and leads users to the right -page if they want to find out more about the package. And make sure the -DESCRIPTION is not overly long. Good descriptions will describe the main -function of the package in a sentence. +Make sure the <c>DESCRIPTION</c> is not overly long. Good descriptions will +describe the main function of the package in a sentence. +</p> + +<p> +Please check if the <c>HOMEPAGE</c> variable is right and leads users to the +right page if they want to find out more about the package. If no homepage for +the package is available, set the <c>HOMEPAGE</c> variable to +<c>https://wiki.gentoo.org/wiki/No_homepage</c>. Please also strive to test +HTTPS support for the site used in <c>HOMEPAGE</c>. </p> </body> @@ -368,8 +457,8 @@ the guidelines to use TABS rather than spaces. So <e>please</e> use tabs! <body> <p> -I'm often guilty of this. Remember to run repoman over your ebuilds so it can -tell you if there is trailing whitespace at the end of lines or on empty lines. +Remember to run <c>pkgcheck</c> over your ebuilds so it can tell you if there +is trailing whitespace at the end of lines or on empty lines. </p> </body> @@ -379,8 +468,8 @@ tell you if there is trailing whitespace at the end of lines or on empty lines. <body> <p> -If <c>S=${WORKDIR}/${P}</c>, then you should not add it to your ebuild. This is -implied already, you should only add it if it is something other than +If <c>S=${WORKDIR}/${P}</c>, then you should not add it to your ebuild. This is +implied already, you should only add it if it is something other than <c>${WORKDIR}/${P}</c>. </p> @@ -392,7 +481,7 @@ implied already, you should only add it if it is something other than <p> If your package has documentation, make sure you install it using <c>dodoc</c> -or in <path>/usr/share/doc/${PF}</path>. Remember to check for errors when +or in <c>/usr/share/doc/${PF}</c>. Remember to check for errors when running <c>dodoc</c>/<c>doins</c>. </p> @@ -420,10 +509,43 @@ at least when the ebuild hits the stable branch. </body> </subsection> +<subsection> +<title>Not using latest EAPI</title> +<body> + +<p> +Often, user-submitted ebuilds do not use the latest EAPI and may even +be several versions behind. EAPIs bring new helper functions and improved +methods for completing common tasks. It's recommended that submitted ebuilds +use the latest EAPI possible (subject to eclass constraints) to improve +the ebuild's quality and ease review. +</p> +</body> +</subsection> + +<subsection> +<title>Calling pkg-config directly</title> +<body> + +<p> +You should not call <c>pkg-config</c> directly in ebuilds because this is +problematic for e.g. cross-compiling. The correct helper respects +<c>${PKG_CONFIG}</c>. Instead, use <c>tc-getPKG_CONFIG</c> from +<c>toolchain-funcs.eclass</c>, e.g. +</p> + +<codesample lang="ebuild"> +sed -i -e "s:-lncurses:$($(tc-getPKG_CONFIG) --libs ncurses):" || die +</codesample> + +<p> +Don't then forget to add <c>virtual/pkgconfig</c> to BDEPEND! +</p> + </body> +</subsection> </section> - <section> <title>Common Ebuild Submission Mistakes</title> <subsection> @@ -431,8 +553,8 @@ at least when the ebuild hits the stable branch. <body> <p> -Please submit ebuilds properly by following the <uri -link="::ebuild-writing/ebuild-maintenance#adding-a-new-ebuild">Adding new Ebuild</uri> tutorial. +Please submit ebuilds properly by following the +<uri link="::ebuild-maintenance/new-ebuild/"/> tutorial. </p> </body> @@ -442,8 +564,8 @@ link="::ebuild-writing/ebuild-maintenance#adding-a-new-ebuild">Adding new Ebuild <body> <p> -Please please please do not attach ebuilds as tarballs. Attach patches -separately as well so we can easily examine them. +Please do not attach ebuilds or patches as tarballs. It avoids extra +operations when reviewing. </p> </body> @@ -470,7 +592,7 @@ of the application, if any exists. </body> </subsection> <subsection> -<title>Package updates without changing the ChangeLog</title> +<title>Package updates without explaining what has changed</title> <body> <p> @@ -484,8 +606,8 @@ It is wise to submit a diff for a package update rather than the whole ebuild. The best way to generate it would be: </p> -<pre caption="Creating a diff"> -$ <i>diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-package-0.2.0.diff</i> +<pre> +$ diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-package-0.2.0.patch </pre> </body> @@ -495,7 +617,7 @@ $ <i>diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-pac <body> <p> -If you are submitting a new version for a package in portage, make sure the +If you are submitting a new version for a package in Portage, make sure the existing ebuild works and make sure changes are incorporated in the new ebuild (such as added documentation.) If there are no required changes to the ebuild from the previous version, then don't attach the ebuild. Just say so in the bug diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml index 3faab22..b6463c0 100644 --- a/ebuild-writing/eapi/text.xml +++ b/ebuild-writing/eapi/text.xml @@ -1,20 +1,21 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/eapi/"> <chapter> <title>EAPI Usage and Description</title> - <body> + <p> -The Package Manager Specification (PMS) is a standardization -effort to ensure that the ebuild file format, the ebuild repository format -(of which the portage tree is Gentoo's main incarnation) as well as behavior -of the package managers interacting with these ebuilds is properly written -down and agreed upon. +The <uri link="https://wiki.gentoo.org/wiki/Project:PMS">Package Manager +Specification (PMS)</uri> is a standardization effort to ensure that the +ebuild file format, the ebuild repository format (of which the Gentoo +repository is Gentoo's main incarnation) as well as behaviour of the package +managers interacting with these ebuilds is properly written down and agreed +upon. </p> <p> EAPI is a version defined in ebuilds and other package manager related files -which inform the package manager about the file syntax and content. It is, +which informs the package manager about the file syntax and content. It is, in effect, the version of the package manager specification (PMS) that the file adheres to. </p> @@ -23,840 +24,1396 @@ file adheres to. This section provides usage and descriptions of the different EAPIs. </p> +</body> + <section> <title>Usage of EAPIs</title> <body> + <important> An overview about the important features of each EAPI is provided in the appendix of the Package Manager Specification. The two-page leaflet can be printed out, consulted for reference and is available as <c>app-doc/pms</c> in the main tree. </important> + <p> -If EAPI is undefined in an ebuild, then EAPI=0 is selected. You should -set the EAPI variable, by specifying it at the top of the ebuild: +You must set the EAPI variable by specifying it at the top of the ebuild: </p> -<note> -Most developers prefer to set the EAPI version without quotes. However, the PMS allows single and double quotes as well. -</note> - <codesample lang="ebuild"> -# Copyright 1999-2013 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -EAPI=5 -inherit eutils +EAPI=7 </codesample> +<note> +Most developers prefer to set the EAPI version without quotes. However, the PMS +allows single and double quotes as well. +</note> + <important> EAPI must only be defined in ebuild files, not eclasses. (eclasses may have EAPI-conditional code) </important> <p> -When writing new ebuilds developers can choose whathever EAPI they think +When writing new ebuilds developers can choose whatever EAPI they think is the best. Using the features of the latest EAPI is encouraged. </p> - </body> -</section> -<section> -<title>EAPI=1</title> +<subsection> +<title>Upgrade path</title> <body> -<ul> - <li> - <p><b>Default src_compile Phase Function</b></p> - <p> - Support for the <c>ECONF_SOURCE</c> variable, which is also supported by - <c>econf</c>, has been added to the default <c>src_compile</c> implementation. - </p> - <codesample lang="ebuild"> -src_compile() { - if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then - econf - fi - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then - emake || die "emake failed" - fi -} - </codesample> - </li> - <li> - <p><b>SLOT dependencies</b></p> - <p> - Any valid atom can be constrained to match a specific SLOT. This - is accomplished by appending a colon to the atom, followed by a - SLOT value. - </p> - <p> - <b>SLOT dependency examples:</b> - <ul> - <li><c>x11-libs/qt:3</c></li> - <li><c>~x11-libs/qt-3.3.8:3</c></li> - <li><c>>=x11-libs/qt-3.3.8:3</c></li> - <li><c>=x11-libs/qt-3.3*:3</c></li> - </ul> - </p> - </li> - <li> - <p><b>IUSE defaults</b></p> - <p> - Add + or - before the name of the use flag in IUSE to turn it on or off by - default. - </p> - - <important> - The default USE-ordering is <c>USE_ORDER="env:pkg:conf:defaults:pkginternal:env.d"</c> - (see man make.conf) - </important> - <important> - Disabling default IUSE is pretty much useless as it does not - override the profile and user config (make.conf and package.use) - </important> - - <codesample lang="ebuild"> -# Copyright 1999-2010 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -EAPI=1 +<p> +Gentoo policy is to support upgrades for installations at least a year old +with no/little intervention and up to two years old with minor intervention. To +achieve this, developers must avoid using the latest EAPI in ebuilds within +the <c>@system</c> set (see <uri link="::general-concepts/dependencies/#implicit-system-dependency"/>) +or its dependencies. +</p> -IUSE="foo +bar" +<p> +The Base System project has +<uri link="https://wiki.gentoo.org/wiki/Project:Base#Rules_and_limitations">rules</uri> +governing their use of newer EAPIs, as does the +<uri link="https://projects.gentoo.org/python/guide/package-maintenance.html#porting-packages-to-a-new-eapi">Python project</uri>. +</p> - </codesample> - </li> -</ul> +<p> +It is also convention that blockers within ebuilds are retained for at least +2 years after the last ebuild matching the block is removed from the tree to +avoid file collisions for users upgrading older systems. <c>pkgcheck</c> has +a warning for this called <c>OutdatedBlocker</c> (or even +<c>NonexistentBlocker</c> for when the match is from pre-git times if using +a non-grafted repository). +</p> </body> +</subsection> </section> - <section> -<title>EAPI=2</title> +<title>EAPIs 0 to 4</title> <body> +<p> +EAPIs 0 to 4 are obsolete and must no longer be used. Refer to the Package +Manager Specification for details about them. +</p> + +</body> +</section> + +<section> +<title>EAPI 5</title> + <subsection> -<title>Helpers</title> +<title>EAPI 5 Metadata</title> <body> -<ul> - <li> - <p><b>doman Language Support</b></p> - <p> - <c>doman</c> automatically detects language codes and puts it in the - appropriate directory. - <codesample lang="ebuild"> -doman foo.1 -# will go into /usr/share/man/man1/foo.1 -doman foo.lang.1 -# will go into /usr/share/man/lang/man1/foo.1 with EAPI=2 - </codesample> - </p> - </li> -</ul> + +<dl> + <dt>REQUIRED_USE supports new at-most-one-of operator</dt> + <dd> + The new <b>at-most-one-of</b> operator consists of the string <c>??</c>, + and is satisfied if zero or one (but no more) of its child elements is + matched. + </dd> + <dt>SLOT supports optional "sub-slot" part</dt> + <dd> + The <c>SLOT</c> variable may contain an optional <b>sub-slot</b> part that + follows the regular slot and is delimited by a <c>/</c> character. + The sub-slot must be a valid slot name. The sub-slot is used to represent + cases in which an upgrade to a new version of a package with a different + sub-slot may require dependent packages to be rebuilt. When the sub-slot + part is omitted from the SLOT definition, the package is considered to have + an implicit sub-slot which is equal to the regular slot. + </dd> + <dt>Slot operators and sub-slots in dependencies</dt> + <dd> + <p> + A slot dependency may contain an optional sub-slot part that follows the + regular slot and is delimited by a <c>/</c> character. This can be useful + for packages installing pre-built binaries that require a library with a + specific soname version which corresponds to the sub-slot. For example: + </p> +<codesample lang="ebuild"> +RDEPEND="dev-libs/foo:0/3" +</codesample> + <p> + Package dependency specifications can use <b>slot operators</b> to clarify + what should happen if the slot and/or sub-slot of a runtime dependency + changes: + </p> + <ul> + <li> + <c>:*</c> Indicates that any slot value is acceptable. In addition, + for runtime dependencies, indicates that the package specifying the + dependency will not break if the package matching the dependency is + replaced by a different matching package with a different slot and/or + sub-slot. + </li> + <li> + <c>:=</c> Indicates that any slot value is acceptable. In addition, + for runtime dependencies, indicates that the package specifying the + dependency will break unless there is available a package matching + the dependency and whose slot and sub-slot are equal to the slot and + sub-slot of the best installed version that had matched this dependency + at the time when the package specifying this dependency had been + installed. + </li> + <li> + <p> + <c>:slot=</c> Indicates that only a specific slot value is acceptable, + and otherwise behaves identically to the <c>:=</c> operator. + </p> + <note> + use <c>:slot/subslot</c> without a <c>=</c> to depend on a specific + slot and sub-slot pair; it's a syntax error to use <c>:slot/subslot=</c> + in an ebuild. + </note> + </li> + </ul> + <p> + The <c>:slot</c> dependency syntax continues to behave like in EAPI=4 or + earlier, i.e. it indicates that only the specific slot value is acceptable, + but the package will not break when the version matching the runtime + dependency is replaced by a version with a different sub-slot. + </p> + <p> + For example: + </p> +<codesample lang="ebuild"> +RDEPEND="dev-libs/foo:2= + >=dev-libs/bar-0.9:= + media-gfx/baz:* + x11-misc/wombat:0" +</codesample> + <p> + means that the package should be rebuilt when <c>foo:2</c> or + <c>>=bar-0.9</c> are upgraded to versions with different subslots, + but that changes in subslots of <c>baz</c> or <c>wombat:0</c> should be + ignored. + </p> + </dd> +</dl> + </body> </subsection> <subsection> -<title>Metadata</title> +<title>EAPI 5 Profiles</title> <body> -<ul> - <li> - <p><b>Blocker Atoms</b></p> - <p> - <ul> - <li> - <p><b>New Meaning for Old Syntax</b></p> - <p> - Blocker atoms which use the previously existing !atom syntax now - have a slightly different meaning. These blocker atoms indicate - that conflicting packages may be temporarily installed - simultaneously. When temporary simultaneous installation of - conflicting packages occurs, the installation of a newer package - may overwrite any colliding files that belong to an older package - which is explicitly blocked. When such file collisions occur, the - colliding files cease to belong to the older package, and they - remain installed after the older package is eventually - uninstalled. The older package is uninstalled only after any newer - blocking packages have been merged on top of it. - </p> - </li> - <li> - <p><b>New !!atom Syntax</b></p> - <p> - A new !!atom syntax is now supported, for use in special cases for - which temporary simultaneous installation of conflicting packages - should not be allowed. If a given package happens to be blocked by - a mixture of atoms consisting of both the !atom and !!atom - syntaxes, the !!atom syntax takes precedence over the !atom - syntax. - </p> - </li> - </ul> - </p> - </li> - <li> - <p><b>USE Dependencies</b></p> - <p> - It is possible to depend on USE-flags of packages. - </p> - <p>Examples: - <ul> - <li><c>foo[bar]</c> means that package foo must have USE-flag bar - enabled</li> - <li><c>foo[bar,baz]</c> means that the package foo must have both - the bar and baz USE-flags enabled - </li> - <li><c>foo[-bar,baz]</c> means that the package foo must have the - bar USE-flag disabled and baz USE-flag enabled</li> - <li><c>foo[bar?]</c> means <c>bar? ( foo[bar] ) !bar? ( foo )</c></li> - <li><c>foo[!bar?]</c> means <c>bar? ( foo ) !bar? ( foo[-bar] )</c></li> - <li><c>foo[bar=]</c> means <c>bar? ( foo[bar] ) !bar? ( foo[-bar] )</c></li> - <li><c>foo[!bar=]</c> means <c>bar? ( foo[-bar] ) !bar? ( foo[bar] )</c></li> - </ul> - </p> - </li> - <li> - <p><b>Customization of Output File Names in SRC_URI</b></p> - <p> - A new syntax is supported which allows customization of the output - file name for a given URI. In order to customize the output file - name, a given URI should be followed by a "<c>-></c>" operator which, in - turn, should be followed by the desired output file name. As - usual, all tokens, including the operator and output file name, - should be separated by whitespace. - </p> - <p>Example:</p> - <codesample lang="ebuild"> -SRC_URI="http://dl.google.com/earth/client/GE4/release_4_3/GoogleEarthLinux.bin - -> GoogleEarthLinux-${PV}.bin" - </codesample> - </li> -</ul> + +<dl> + <dt>Profile stable USE forcing and masking</dt> + <dd> + In profile directories with an EAPI supporting stable masking, new USE + configuration files are supported: <c>use.stable.mask</c>, + <c>use.stable.force</c>, <c>package.use.stable.mask</c> and + <c>package.use.stable.force</c>. These files behave similarly to previously + supported USE configuration files, except that they only influence packages + that are merged due to a stable keyword. + </dd> +</dl> </body> </subsection> <subsection> -<title>Phases</title> +<title>EAPI 5 Helpers</title> <body> -<ul> - <li> - <p><b>New <c>src_prepare</c> Phase Function</b></p> - <p> - A new src_prepare function is called after the <c>src_unpack</c> - function, with cwd initially set to <c>$S</c>. - </p> - </li> - <li> - <p><b>New <c>src_configure</c> Phase Function</b></p> - <p> - The configure portion of the <c>src_compile</c> function has been split - into a separate function which is named <c>src_configure</c>. The - <c>src_configure</c> function is called in-between the <c>src_prepare</c> and - <c>src_compile</c> functions. - </p> - <p>The default <c>src_configure</c> and <c>src_compile</c> - functions in EAPI=2: - <codesample lang="ebuild"> -src_configure() { - if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then - econf - fi -} -src_compile() { - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then - emake || die "emake failed" - fi -} - </codesample> - </p> - </li> - <li> - <p><b>Execution Order of Phase Functions</b></p> - <p> - <ul> - <li><c>pkg_setup</c></li> - <li><c>src_unpack</c></li> - <li><c>src_prepare</c></li> - <li><c>src_configure</c></li> - <li><c>src_compile</c></li> - <li><c>src_test</c></li> - <li><c>src_install</c></li> - <li><c>pkg_preinst</c></li> - <li><c>pkg_postinst</c></li> - <li><c>pkg_prerm</c></li> - <li><c>pkg_postrm</c></li> - </ul> - </p> - </li> - <li> - <p><b>Default Phase Functions</b></p> - <p> - The default <c>pkg_nofetch</c> and <c>src_*</c> phase functions are now - accessible via a function having a name that begins with <c>default_</c> - and ends with the respective phase function name. For example, a - call to a function with the name <c>default_src_compile</c> is equivalent - to a call to the default <c>src_compile</c> implementation. - </p> - <p>The default phase functions are: - <ul> - <li><c>default_pkg_nofetch</c></li> - <li><c>default_src_unpack</c></li> - <li><c>default_src_prepare</c></li> - <li><c>default_src_configure</c></li> - <li><c>default_src_compile</c></li> - <li><c>default_src_test</c></li> - </ul> - </p> - </li> - <li> - <p><b>Default Phase Function Alias</b></p> - <p> - A function named "<c>default</c>" is redefined for each phase so that it - will call the <c>default_*</c> function corresponding to the current - phase. For example, a call to the function named "<c>default</c>" during - the <c>src_compile</c> phase is equivalent to a call to the function - named <c>default_src_compile</c>. - </p> - </li> -</ul> +<dl> + <dt>econf adds --disable-silent-rules</dt> + <dd> + This option will automatically be passed if <c>--disable-silent-rules</c> + occurs in the output of <c>configure --help</c>. + </dd> + <dt>new* commands can read from standard input</dt> + <dd> + Standard input is read when the first parameter is <c>-</c> (a hyphen). + </dd> + <dt>New option --host-root for {has,best}_version</dt> + <dd> + This option <c>--host-root</c> will cause the query to apply to the host + root instead of ROOT. + </dd> + <dt>New doheader helper function</dt> + <dd> + Installs the given header files into <c>/usr/include/</c>. If option + <c>-r</c> is specified, descends recursively into any directories given. + </dd> + <dt>New usex helper function</dt> + <dd> + <!-- We probably need an example here --> +<pre> +USAGE: usex <USE flag> [true output] [false output] [true suffix] [false suffix] +DESCRIPTION: +If USE flag is set, echo [true output][true suffix] (defaults to "yes"), + otherwise echo [false output][false suffix] (defaults to "no"). +</pre> + </dd> +</dl> + </body> </subsection> +<subsection> +<title>EAPI 5 Phases</title> +<body> + +<dl> + <dt>src_test supports parallel tests</dt> + <dd> + Unlike older EAPIs, the default <c>src_test</c> implementation will not + pass the -j1 option to emake. + </dd> +</dl> + </body> -</section> -<section> -<title>EAPI=3</title> +</subsection> + +<subsection> +<title>EAPI 5 Variables</title> <body> -<ul> - <li> - <p><b>Gentoo Prefix support</b></p> - <p> - Support for the <c>EPREFIX</c>, <c>EROOT</c>, and <c>ED</c> - variables. If an ebuild uses one of these, it must be EAPI3 aware. - See <uri link="http://www.gentoo.org/proj/en/gentoo-alt/prefix/techdocs.xml#doc_chap2">Gentoo Prefix Techdocs</uri> for more information. - </p> - </li> - <li> - <p><b>unpack supports .xz and .tar.xz</b></p> - <p> - The <c>unpack</c> command supports xz-archives and xz-compressed tar - files. - </p> - </li> -</ul> +<dl> + <dt>EBUILD_PHASE_FUNC</dt> + <dd> + During execution of an ebuild phase function (such as <c>pkg_setup</c> or + <c>src_unpack</c>), the <c>EBUILD_PHASE_FUNC</c> variable will contain the + name of the phase function that is currently executing. + </dd> +</dl> </body> +</subsection> </section> <section> -<title>EAPI=4</title> -<body> +<title>EAPI 6</title> <subsection> -<title>Helpers</title> +<title>EAPI 6 Bash version</title> <body> -<ul> - <li> - <p><b>utilities die on their own, unless the nonfatal command is used</b></p> - <p> - <!-- TODO link auf fuunction-reference --> - Ebuild functions all die on their own in EAPI=4. In case that this - non-zero exit status is expected, you may call <c>nonfatal function - [arg,...]</c>. - </p> - <p>Example:</p> - <codesample lang="ebuild"> -EAPI=1 -... -src_install() { - emake DESTDIR="${D}" install || die "make install failed" - dodoc ChangeLog README -} - </codesample> - <codesample lang="ebuild"> -EAPI=4 -... -src_install() { - emake DESTDIR="${D}" install - nonfatal dodoc ChangeLog README -} - </codesample> - </li> - <li> - <p><b>recursive dodoc</b></p> - <p> - <c>dodoc</c> supports <c>-r</c> as the first argument, which leads - <c>dodoc</c> to install the specified documentation directory - recursively into the docdir. - </p> - <p>Example:</p> - <codesample lang="ebuild"> -src_install() { - default - dodoc ChangeLog - dodoc -r doc/ -} - </codesample> - </li> - <li> - <p><b>doins symlink supports</b></p> - <p> - Within EAPI=4, <c>doins</c> supports installing symlinks as symlinks - when installing recursively. For older EAPIs, the symlink behaviour - is undefined. - </p> - </li> - <li> - <p><b>dosed and dohard are banned</b></p> - <p> - The <c>dosed</c> and <c>dohard</c> commands are banned in this EAPI. - </p> - </li> - <li> - <p><b>econf adds --disable-dependency-tracking</b></p> - <p> - Within EAPI=4, <c>econf</c> adds - <c>--disable-dependency-tracking</c> to the default configure - options. - </p> - </li> - <li> - <p><b>controllable compression via docompress</b></p> - <p> - To compress files in the destination-folder <c>${D}</c>, the - <c>docompress</c> command may be used in <c>src_install</c>. - To control which items should be compressed and which shouldn't - be compressed, you may include or exclude directories or plain - files. The default inclusion list contains: - <ul> - <li><c>/usr/share/doc</c></li> - <li><c>/usr/share/info</c></li> - <li><c>/usr/share/man</c></li> - </ul> - The default exclusion list contains: - <ul> - <li><c>/usr/share/doc/${PF}/html</c></li> - </ul> - When a directory is in- or excluded, all files and directories in - the given directories shall be added to the corresponding list. - If a file is in- or excluded, the file shall be added to the - corresponding list (exclusion is stronger than inclusion <d/> - if a file is in both lists, the inclusion will be ignored). - </p> - <p> - If the first argument of <c>docompress</c> is <c>-x</c>, the items - specified will be added to the exclusion list, otherwise they will - be added to the inclusion list. - </p> - <note> - When <c>docompress</c> is called, it is <e>not</e> required that - the paths specified as its arguments are pointing to existing files - or directories. However, if a file still doesn't exist when - <c>src_install</c> has completed, it will be ignored with a - warning. - </note> - </li> -</ul> + +<dl> + <dt>Bash version</dt> + <dd> + Ebuilds can use features of Bash version 4.2 (was 3.2 before). + </dd> +</dl> + </body> </subsection> <subsection> -<title>Metadata</title> +<title>EAPI 6 Ebuild Environment</title> <body> -<ul> - <li> - <p><b>use dependencies default</b></p> - <p> - In addition to the use-deps specified in EAPI=2, a <c>(+)</c> or - <c>(-)</c> may be added to the use-dep to define a default-value in - case the use-flag does not exist in the given package. The - <c>(+)</c> means that this use-flag is assumed to be enabled, - <c>(-)</c> the opposite. - <p>Example:</p> - <codesample lang="ebuild"> -DEPEND=" - >=dev-libs/boost-1.32[boost(+)] - sys-devel/gcc[openmp(-)]" - </codesample> - </p> - </li> -</ul> + +<dl> + <dt>Locale settings</dt> + <dd> + Behaviour of case modification and collation order (<c>LC_CTYPE</c> and + <c>LC_COLLATE</c>) are guaranteed to be the same as in the C locale, as far + as characters in the ASCII range are concerned. + </dd> + <dt><c>failglob</c> enabled</dt> + <dd> + For <c>EAPI=6</c>, the <c>failglob</c> option of bash is set in the global + scope of ebuilds. If set, failed pattern matches during filename expansion + result in an error when the ebuild is being sourced. + </dd> +</dl> + </body> </subsection> <subsection> -<title>Phases</title> +<title>EAPI 6 Phases</title> <body> -<ul> - <li> - <p><b>new pkg_pretend phase</b></p> - <p> - The new <c>pkg_pretend</c> phase can be used to do sanity checks - before the main phase function sequence is run (meaning this phase is - executed after the package manager has calculated the dependencies - and before installing them). - This phase typically checks for a kernel configuration and may - <c>eerror</c> and <c>die</c> when needed. - <important> - There is no guarantee that the ebuild's dependencies are installed - when this phase is called. - </important> - <important> - As <c>pkg_pretend</c> is not called in the main phase function - sequence, environment saving is not guaranteed. - </important> - </p> - <p>Example:</p> - <codesample lang="ebuild"> -# Copyright 1999-2009 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -EAPI=4 -inherit linux-info -... - -CONFIG_CHECK="FUSE_FS" -ERROR_FUSE_FS="this is an unrealistic testcase..." - -pkg_pretend() { - if use kernel_linux ; then - if [[ -e "${ROOT}"/usr/src/linux/.config ]] ; then - if kernel_is lt 2 6 30 ; then - check_extra_config - fi - fi - fi + +<dl> + <dt>Update default implementation of <c>src_prepare</c></dt> + <dd> + <p> + This phase is no longer a no-op, it supports applying patches via the + <c>PATCHES</c> variable and applying user patches via <c>eapply_user</c>. + The default <c>src_prepare</c> looks like this: + </p> +<codesample lang="ebuild"> +src_prepare() { + if [[ $(declare -p PATCHES 2>/dev/null) == "declare -a"* ]]; then + [[ -n ${PATCHES[@]} ]] && eapply "${PATCHES[@]}" + else + [[ -n ${PATCHES} ]] && eapply ${PATCHES} + fi + eapply_user } - </codesample> - </li> - <li> - <p><b>default src_install is no longer a no-op</b></p> - <p> - The default <c>src_install</c> function in EAPI=4: - </p> - <codesample lang="ebuild"> +</codesample> + </dd> + <dt>New <c>src_install</c> Phase Function</dt> + <dd> + <p> + This phase uses the new <c>einstalldocs</c> function for installation of + documentation. The default <c>src_install</c> looks like this: + </p> +<codesample lang="ebuild"> src_install() { - if [[ -f Makefile ]] || [[ -f GNUmakefile]] || [[ -f makefile ]] ; then - emake DESTDIR="${D}" install - fi - - if ! declare -p DOCS >/dev/null 2>&1 ; then - local d - for d in README* ChangeLog AUTHORS NEWS TODO CHANGES THANKS BUGS \ - FAQ CREDITS CHANGELOG ; do - [[ -s "${d}" ]] && dodoc "${d}" - done - elif declare -p DOCS | grep -q "^declare -a " ; then - dodoc "${DOCS[@]}" - else - dodoc ${DOCS} - fi + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then + emake DESTDIR="${D}" install + fi + einstalldocs } - </codesample> - </li> - <li> - <p><b>pkg_info for non-installed packages</b></p> - <p> - The <c>pkg_info</c> function may also be called by the - package manager for non-installed packages. - Ebuild writers should note that dependencies may not be - available. - </p> - </li> -</ul> +</codesample> + </dd> +</dl> + </body> </subsection> <subsection> -<title>Variables</title> +<title>EAPI 6 Helpers</title> <body> -<ul> - <li> - <p><b>REQUIRED_USE</b></p> - <p> - The <c>REQUIRED_USE</c> variable contains a list of assertions that - must be met by the configuration of USE flags to be valid for this - ebuild. In order to be matched, a USE flag in a terminal element - must be enabled (or disabled if it has an exclamation mark prefix). - </p> - <p> - Essentially, <c>REQUIRED_USE</c> is an analogue of <c>DEPEND</c> - style syntax. For example, to state that some combination is - forbidden, i.e. "if <c>foo</c> is set, <c>bar</c> must be unset": - </p> - <codesample lang="ebuild"> -REQUIRED_USE="foo? ( !bar )" - </codesample> - <p> - To state "if <c>foo</c> is set, then at least one of <c>bar</c>, - <c>baz</c>, and <c>quux</c> must be activated": - </p> - <codesample lang="ebuild"> -REQUIRED_USE="foo? ( || ( bar baz quux ) )" - </codesample> - <p> - To state "exactly one of <c>foo</c>, <c>bar</c>, or <c>baz</c> must - be set, but not several": - </p> - <codesample lang="ebuild"> -REQUIRED_USE="^^ ( foo bar baz )" - </codesample> - <p> - Note that the last relationship is that of an Exclusive OR (XOR). - While an XOR could be formed from usual <c>DEPEND</c> syntax, a - specific <c>^^</c> operator has been added for this case. - </p> - <p> - Finally, to state "at least one of <c>foo</c>, <c>bar</c>, or - <c>baz</c> must be set": - </p> - <codesample lang="ebuild"> -REQUIRED_USE="|| ( foo bar baz )" - </codesample> - - <important> - See section - <uri link="::general-concepts/use-flags/#conflicting-use-flags" /> - for when (and when not) to use <c>REQUIRED_USE</c>. - </important> - </li> - <li> - <p><b>REPLACING_VERSIONS and REPLACED_BY_VERSION</b></p> - <p> - The <c>REPLACING_VERSIONS</c> variable contains a - whitespace-separated list of all versions (<c>PVR</c>) of this - package that are being replaced (uninstalled or overwritten) as a - result of this install. It is a list, not a single optional value, - to handle pathological cases such as installing <c>foo-2:2</c> to - replace <c>foo-2:1</c> and <c>foo-3:2</c>. - </p> - <p> - <c>REPLACING_VERSIONS</c> is valid in <c>pkg_preinst</c> and - <c>pkg_postinst</c>. In addition, it may be available in - <c>pkg_pretend</c> and <c>pkg_setup</c>, although you should take - care to handle binary package creation and installation correctly - when using it in these phases. - </p> - <p> - The <c>REPLACED_BY_VERSION</c> variable contains the single version - (<c>PVR</c>) of this package that is replacing us, if we are being - uninstalled as part of an install, or an empty string otherwise. - It is valid in <c>pkg_prerm</c> and <c>pkg_postrm</c>. - </p> - </li> - <li> - <p><b>MERGE_TYPE</b></p> - <p> - The <c>MERGE_TYPE</c> variable contains the type of package that - is being merged. Possible values are: - <dl> - <dt><c>source</c></dt> - <dd><p> - if building and installing a package from source, - </p></dd> - <dt><c>binary</c></dt> - <dd><p> - if installing a binary package, - </p></dd> - <dt><c>buildonly</c></dt> - <dd><p> - if building a binary package without installing it. - </p></dd> - </dl> - </p> - </li> - <li> - <p><b>DOCS</b></p> - <p> - The <c>DOCS</c> variable is an array or whitespace-separated list - of documentation files for the default <c>src_install</c> function - to install using <c>dodoc</c>. If undefined, a reasonable default - list is used. See the default <c>src_install</c> function above. - </p> - </li> - <li> - <p><b>AA and KV variables are gone</b></p> - <p> - The <c>AA</c> and <c>KV</c> variables are no longer set in EAPI=4. - </p> - </li> - <li> - <p><b>no more RDEPEND="${DEPEND}"</b></p> - <p> - When <c>RDEPEND</c> is unset, there will no longer be an automatic - assignment of <c>RDEPEND="${DEPEND}"</c>. - </p> - </li> -</ul> -</body> -</subsection> + +<dl> + <dt><c>einstall</c> banned</dt> + <dd> + The <c>einstall</c> helper has been banned with <c>EAPI=6</c>. + </dd> + <dt><c>dohtml</c> deprecated</dt> + <dd> + The <c>dohtml</c> helper has been deprecated with <c>EAPI=6</c>. + </dd> + <dt><c>nonfatal die</c></dt> + <dd> + When <c>die</c> or <c>assert</c> are called under the <c>nonfatal</c> + command and with the <c>-n</c> option, they will not abort the build + process but return with an error. + </dd> + <dt><c>eapply</c> support</dt> + <dd> + The <c>eapply</c> command is a simplified substitute for <c>epatch</c> + (from <c>eutils.eclass</c>), implemented in the package manager. + The patches from its file or directory arguments are applied using patch + <c>-p1</c>, but it accepts <c>patch(1)</c> options from GNU patch to + override default behavior. + </dd> + <dt><c>eapply_user</c> support</dt> + <dd> + <p> + The <c>eapply_user</c> command permits the package manager to apply + user-provided patches. It must be called from every <c>src_prepare</c> + function. + </p> + <note> + <c>eapply_user</c> doesn't need to be called explicitly when default + <c>src_prepare</c> is called. + </note> + </dd> + <dt><c>econf</c> adds <c>--docdir</c> and <c>--htmldir</c></dt> + <dd> + Options <c>--docdir</c> and <c>--htmldir</c> are passed to + <c>configure</c>, in addition to the existing options. + </dd> + <dt><c>in_iuse</c> support</dt> + <dd> + The <c>in_iuse</c> function returns <c>true</c> if the given parameter is + available in the ebuilds <c>USE</c>. + </dd> + <dt><c>unpack</c> changes</dt> + <dd> + <ul> + <li> + <c>unpack</c> supports relative paths without leading <c>./</c> + (<c>unpack foo/bar.tar.gz</c> is valid as relative path). + </li> + <li><c>unpack</c> supports <c>.txz</c> (xz compressed tarball).</li> + <li><c>unpack</c> matches filename extensions case-insensitively.</li> + </ul> + </dd> + <dt><c>einstalldocs</c> support</dt> + <dd> + The <c>einstalldocs</c> function will install the files specified by the + <c>DOCS</c> variable (or a default set of files if <c>DOCS</c> is unset) + and by the <c>HTML_DOCS</c> variable. + </dd> + <dt><c>get_libdir</c> support</dt> + <dd> + The <c>get_libdir</c> command outputs the <c>lib*</c> directory basename + suitable for the current ABI. + </dd> +</dl> </body> +</subsection> </section> <section> -<title>EAPI=5</title> +<title>EAPI 7</title> + +<subsection> +<title>EAPI 7 Terminology</title> <body> +<p> +Documents may use the following terms to better describe dependency and +installation targets. +</p> + +<dl> + <dt><c>CHOST</c></dt> + <dd> + The system that will be running the installed package. + </dd> + <dt><c>CBUILD</c></dt> + <dd> + The system used to build packages. When not cross-compiling, + CBUILD == CHOST. + </dd> + <dt><c>CTARGET</c></dt> + <dd> + Used in certain cross-compilations, often empty value. + </dd> +</dl> + +</body> +</subsection> + <subsection> -<title>Metadata</title> +<title>EAPI 7 Variables</title> <body> -<ul> - <li> - <p><b>REQUIRED_USE supports new at-most-one-of operator</b></p> - <p> - The new <b>at-most-one-of</b> operator consists of the string <c>'??'</c>, and is satisfied if zero or one (but no more) of its child elements is matched. - </p> - </li> - <li> - <p><b>SLOT supports optional "sub-slot" part</b></p> - <p> - The <c>SLOT</c> variable may contain an optional <b>sub-slot</b> part that follows the regular slot and is delimited by a <c>/</c> character. The sub-slot must be a valid slot name. The sub-slot is used to represent cases in which an upgrade to a new version of a package with a different sub-slot may require dependent packages to be rebuilt. When the sub-slot part is omitted from the SLOT definition, the package is considered to have an implicit sub-slot which is equal to the regular slot. - </p> - </li> - <li> - <p><b>Slot operators and sub-slots in dependencies</b></p> - <p> - A slot dependency may contain an optional sub-slot part that follows the regular slot and is delimited by a <c>/</c> character. This can be useful for packages installing pre-built binaries that require a library with a specific soname version which corresponds to the sub-slot. For example: - </p> - <codesample lang="ebuild"> -RDEPEND="dev-libs/foo:0/3" - </codesample> - <p> - Dependency atoms can use <b>slot operators</b> to clarify what should happen if the slot and/or sub-slot of a runtime dependency changes: - </p> - <ul> - <li> - <c>:*</c> Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package specifying the dependency will not break if the package matching the dependency is replaced by a different matching package with a different slot and/or sub-slot. - </li> - <li> - <c>:=</c> Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package specifying the dependency will break unless there is available a package matching the dependency and whose slot and sub-slot are equal to the slot and sub-slot of the best installed version that had matched this dependency at the time when the package specifying this dependency had been installed. - </li> - <li> - <c>:slot=</c> Indicates that only a specific slot value is acceptable, and otherwise behaves identically to the <c>:=</c> operator. - <note> - use <c>:slot/subslot</c> without a <c>=</c> to depend on a specific slot and sub-slot pair; it's a syntax error to use <c>:slot/subslot=</c> in an ebuild. - </note> - </li> - </ul> - <p> - The <c>:slot</c> dependency syntax continues to behave like in EAPI=4 or earlier, i.e. it indicates that only the specific slot value is acceptable, but the package will not break when the version matching the runtime dependency is replaced by a version with a different sub-slot. - </p> - <p> - For example: - </p> - <codesample lang="ebuild"> -RDEPEND="dev-libs/foo:2= - >=dev-libs/bar-0.9:= - media-gfx/baz:* - x11-misc/wombat:0" - </codesample> - <p> - means that the package should be rebuilt when <c>foo:2</c> or <c>>=bar-0.9</c> are upgraded to versions with different subslots, but that changes in subslots of <c>baz</c> or <c>wombat:0</c> should be ignored. - </p> - </li> -</ul> + +<dl> + <dt><c>PORTDIR</c> and <c>ECLASSDIR</c> are removed</dt> + <dd> + <c>PORTDIR</c> and <c>ECLASSDIR</c> are no longer defined and cannot be + used in ebuilds to access these directories. + </dd> + <dt><c>DESTTREE</c> and <c>INSDESTTREE</c> are removed</dt> + <dd> + The unintended exported variables <c>PORTDIR</c> and <c>ECLASSDIR</c> + cannot be used in ebuilds to manipulate installation paths. Use <c>into</c> + or <c>insinto</c>, respectively, instead. + </dd> + <dt><c>D</c>, <c>ED</c>, <c>ROOT</c>, and <c>EROOT</c> modified</dt> + <dd> + These variables no longer contain a trailing slash with <c>EAPI=7</c>. + </dd> + <dt><c>BDEPEND</c> added</dt> + <dd> + Previously, all build-time tools and libraries went into the <c>DEPEND</c>. + Now, built-time dependencies are split into <c>DEPEND</c> and + <c>BDEPEND</c>. The difference is simply that <c>BDEPEND</c> are + dependencies to be executed on the CBUILD. <c>DEPEND</c> remains for other + dependencies, such as libraries, for the CHOST. This improves the + cross-compilation support. + </dd> + <dt><c>BROOT</c> added</dt> + <dd> + <c>BROOT</c> is the absolute path to the root directory, including any + prefix, containing build dependencies satisfied by BDEPEND, typically + executable build tools. + </dd> + <dt><c>SYSROOT</c> and <c>ESYSROOT</c> added</dt> + <dd> + <c>SYSROOT</c> is the location of where dependencies in <c>DEPEND</c> are + installed. <c>ESYSROOT</c> is <c>SYSROOT</c> with <c>EPREFIX</c> appended. + </dd> + <dt><c>ENV_UNSET</c> added</dt> + <dd> + A whitespace delimited list of variables to be removed from the build + environment. + </dd> +</dl> + </body> </subsection> <subsection> -<title>Profiles</title> +<title>EAPI 7 Metadata</title> <body> -<ul> - <li> - <p><b>Profile stable USE forcing and masking</b></p> - <p> - In profile directories with an EAPI supporting stable masking, new USE configuration files are supported: <c>use.stable.mask</c>, <c>use.stable.force</c>, <c>package.use.stable.mask</c> and <c>package.use.stable.force</c>. These files behave similarly to previously supported USE configuration files, except that they only influence packages that are merged due to a stable keyword. - </p> - </li> -</ul> + +<dl> + <dt>Empty groupings are banned</dt> + <dd> + Groupings which are empty, such as <c>DEPEND="|| ( ${empty_var} )"</c> + will now generate an error. Furthermore, conditions within groupings are + more strictly enforced. For example, <c>REQUIRED_USE="|| ( foo? ( bar ) + baz? ( zoinks )"</c> would previously work with <c>USE="-foo -baz"</c> + now requires either <c>USE="foo bar"</c> or <c>USE="baz zoinks"</c>. + </dd> +</dl> + </body> </subsection> <subsection> -<title>Helpers</title> +<title>EAPI 7 Profiles</title> <body> -<ul> - <li> - <p><b>econf adds --disable-silent-rules</b></p> - <p> - This option will automatically be passed if <c>--disable-silent-rules</c> occurs in the output of <c>configure --help</c>. - </p> - </li> - <li> - <p><b>new* commands can read from standard input</b></p> - <p> - Standard input is read when the first parameter is <c>-</c> (a hyphen). - </p> - </li> - <li> - <p><b>New option --host-root for {has,best}_version</b></p> - <p> - This option <c>--host-root</c> will cause the query to apply to the host root instead of ROOT. - </p> - </li> - <li> - <p><b>New doheader helper function</b></p> - <p> - Installs the given header files into <c>/usr/include/</c>, by default with file mode <c>0644</c>. This can be overridden by setting <c>INSOPTIONS</c> with the <c>insopts</c> function. - </p> - </li> - <li> - <p><b>New usex helper function</b></p> - <p> - <!-- We probably need an example here --> - <pre> -USAGE: usex 〈USE flag〉 [true output] [false output] [true suffix] [false suffix] -DESCRIPTION: -If USE flag is set, echo [true output][true suffix] (defaults to "yes"), - otherwise echo [false output][false suffix] (defaults to "no"). - </pre> - </p> - </li> -</ul> + +<dl> + <dt><c>package.provided</c> banned</dt> + <dd> + Profiles may no longer contain a <c>package.provided</c> file with + <c>EAPI=7</c>. + </dd> +</dl> + </body> </subsection> <subsection> -<title>Phases</title> +<title>EAPI 7 Helpers</title> <body> -<ul> - <li> - <p><b>src_test supports parallel tests</b></p> - <p> - Unlike older EAPIs, the default <c>src_test</c> implementation will not pass the -j1 option to emake. - </p> - </li> -</ul> + +<dl> + <dt><c>dohtml</c> banned</dt> + <dd> + The <c>dohtml</c> helper has been banned with <c>EAPI=7</c>. + </dd> + <dt><c>dolib</c> and <c>libopts</c> banned</dt> + <dd> + The <c>dolib</c> helper and the associated <c>libopts</c> have been banned + with <c>EAPI=7</c>. + </dd> + <dt><c>has_version</c> and <c>best_version</c> changes</dt> + <dd> + <p> + <c>has_version</c> and <c>best_version</c> now support an optional switch + to determine which type of dependencies to check. + </p> + <ul> + <li><c>-r</c> (the default) will check runtime dependencies (RDEPEND)</li> + <li><c>-d</c> will check CHOST build-time dependencies (DEPEND)</li> + <li><c>-b</c> will check CBUILD build-time dependencies (BDEPEND)</li> + </ul> + </dd> + <dt>Version manipulation and comparison commands</dt> + <dd> + <p> + EAPI=7 introduced three commands for common version number operations. + </p> + <ul> + <li><c>ver_cut</c> obtains substrings of a version string</li> + <li><c>ver_rs</c> replaces separators in a version string</li> + <li><c>ver_test</c> compares two versions</li> + </ul> + <p> + See <uri link="::ebuild-writing/variables/#Version and Name Formatting Issues"/> + for examples of common uses or + <uri link="https://dev.gentoo.org/~mgorny/articles/the-ultimate-guide-to-eapi-7.html#version-manipulation-and-comparison-commands"> + an in-depth look</uri> + </p> + </dd> + <dt>New function <c>eqawarn</c></dt> + <dd> + The <c>eqawarn</c> helper has been added with <c>EAPI=7</c>. This function + is to alert developers to a deprecated feature. Previously, this was + contained in <c>eutils</c> eclass which is no longer necessary. + </dd> + <dt>New function <c>dostrip</c></dt> + <dd> + The <c>dostrip</c> helper has been added with <c>EAPI=7</c>. This function + controls whether or not to strip a binary. <c>dostrip -x [file]</c> will + exclude a binary from being stripped. Conversely, when combined with + RESTRICT=strip, <c>dostrip [file]</c> selects a binary file to be stripped. + </dd> + <dt><c>die</c> and <c>assert</c> changes</dt> + <dd> + These commands are now safe to use in a subshell and act as if they were + called in the main process. + </dd> + <dt><c>nonfatal</c> changes</dt> + <dd> + The <c>nonfatal</c> command now works for shell functions and subprocesses. + </dd> + <dt><c>domo</c> behaviour changed</dt> + <dd> + <c>domo</c> (for localizations) now ignores the <c>into</c> directives. + This follows similar commands like <c>doinfo</c> and <c>doman</c>. + </dd> + <dt><c>econf</c> changes</dt> + <dd> + The cross-compilation options <c>--build</c> and <c>--target</c> options + to specify <c>CBUILD</c> and <c>CTARGET</c> respectively have been added + and are retro-active to all EAPIs. In addition, if the build supports + <c>--with-sysroot</c>, the correct value will be passed such that normal + and cross-compilations succeed. + </dd> +</dl> + </body> </subsection> +</section> + +<section> +<title>EAPI 8</title> +<body> + +<note> +This section is based on +<uri link="https://mgorny.pl/articles/the-ultimate-guide-to-eapi-8.html"> +The ultimate guide to EAPI 8</uri> by Michał Górny. +</note> + +</body> <subsection> -<title>Variables</title> +<title>EAPI 8 tree layout</title> <body> -<ul> - <li> - <p><b>EBUILD_PHASE_FUNC</b></p> - <p> - During execution of an ebuild phase function (such as <c>pkg_setup</c> or <c>src_unpack</c>), - the <c>EBUILD_PHASE_FUNC</c> variable will contain the name of the phase function that is currently executing. - </p> - </li> -</ul> + +<dl> + <dt>Less strict naming rules for updates directory</dt> + <dd> + <p> + Up to EAPI 7, the files in the <c>profiles/updates</c> directory had to + follow strict naming by quarters like <c>2Q-2021</c>, indicating the + quarter and the year when they were added. Such a choice of name had the + side effect that lexical sorting of filenames was unsuitable. + </p> + + <p> + In EAPI 8, the naming requirement is removed. Eventually, this will allow + switching to a more convenient scheme sorted by year. Different lengths + of time periods will also be possible. + </p> + + <p> + Note that this change actually requires changing the repository EAPI + (found in <c>profiles/eapi</c>), so it will not affect Gentoo for at least + the next two years. + </p> + </dd> +</dl> + </body> </subsection> +<subsection> +<title>EAPI 8 ebuild format</title> +<body> + +<dl> + <dt>Bash version is now 5.0</dt> + <dd> + <p> + The Bash version used for ebuilds is changed from 4.2 to 5.0. This means + not only that ebuilds are now permitted to use features provided by the new + Bash version but also the <c>BASH_COMPAT</c> value used for the ebuild + environment is updated, switching the shell behaviour. + </p> + + <p> + The only really relevant difference in behaviour is: + </p> + + <ul> + <li> + <p> + Quotes are now removed from the RHS argument of a + <c>"${var/.../"..."}"</c> substitution: + </p> + +<pre> +var=foo +echo "${var/foo/"bar"}" +</pre> + + <p> + The above snippet yields <c>"bar"</c> in Bash 4.2 but just <c>bar</c> + in 4.3+. + </p> + </li> + </ul> + + <p> + Potentially interesting new features include: + </p> + + <ul> + <li> + <p> + Negative subscripts can now be used to set and unset array elements + (Bash 4.3+): + </p> + +<pre> +$ foo=( 1 2 3 ) +$ foo[-1]=4 +$ unset 'foo[-2]' +$ declare -p foo +declare -a foo=([0]="1" [2]="4") +</pre> + + </li> + <li> + <p> + Nameref variables are introduced that work as references to other + variables (4.3+): + </p> + +<pre> +$ foo=( 1 2 3 ) +$ declare -n bar=foo +$ echo "${bar[@]}" +1 2 3 +$ bar[0]=4 +$ echo "${foo[@]}" +4 2 3 +$ declare -n baz=foo[1] +$ echo "${baz}" +2 +$ baz=100 +$ echo "${bar[@]}" +4 100 3 +</pre> + + </li> + <li> + <p> + The <c>[[ -v ... ]]</c> test operator can be used with array indices + to test for array elements being set (4.3+). The two following lines + are now equivalent: + </p> + +<pre> +[[ -n ${foo[3]+1} ]] +[[ -v foo[3] ]] +</pre> + </li> + <li> + <p> + <c>mapfile</c> (AKA <c>readarray</c>) now accepts a delimiter via + <c>-d</c>, with a <c>-t</c> option to strip it from read data + (Bash 4.4+). The two following solutions to grab output from + <c>find(1)</c> are now equivalent: + </p> + +<pre> +# old solution +local x files=() +while read -d '' -r x; do + files+=( "${x}" ) +done < <(find -print0) + +# new solution +local files=() +mapfile -d '' -t files < <(find -print0) +</pre> + + </li> + <li> + <p> + A new set of transformations is available via <c>${foo@...}</c> + parameter expansion (4.4+), e.g. to print a value with necessary + quoting: + </p> + +<pre> +$ var="foo 'bar' baz" +$ echo "${var@Q}" +'foo '\''bar'\'' baz' +</pre> + + <p> + For more details, see: <c>info bash</c> or the + <uri link="https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html"> + Bash reference manual</uri>. + </p> + </li> + <li> + <p> + <c>local -</c> can be used to limit single-letter (mangled via + <c>set</c>) shell option changes to the scope of the function, and + restore them upon returning from it (4.4+). The following two functions + are now equivalent: + </p> + +<pre> +# old solution +func() { + local prev_shopt=$(shopt -p -o noglob) + set -o noglob + ${prev_shopt} +} + +# new solution +func() { + local - + set -o noglob +} +</pre> + + <p> + The complete information on all changes and new features can be found + in the + <uri link="https://git.savannah.gnu.org/cgit/bash.git/tree/NEWS?h=bash-5.0"> + Bash 5.0 (and earlier) release notes</uri>. + </p> + </li> + </ul> + </dd> +</dl> </body> -</section> +</subsection> +<subsection> +<title>EAPI 8 variables</title> +<body> + +<dl> + <dt>Selective fetch/mirror restriction</dt> + <dd> + <p> + Before EAPI 8, fetch and mirror restrictions applied globally. That is, + if you needed to apply the respective restriction to at least one distfile, + you had to apply it to them all. However, sometimes packages used a + combination of proprietary and free distfiles, the latter including e.g. + third party patches, artwork. Until now, they had to be mirror-restricted + completely. + </p> + + <p> + EAPI 8 allows undoing fetch and mirror restriction for individual files. + To use this, set <c>RESTRICT</c> as before, then use the special + <c>fetch+</c> prefix to specify URLs that can be fetched from, or the + <c>mirror+</c> prefix to reenable mirroring of individual files. + </p> + + <p> + Similarly to how the <c>fetch</c> restriction implies a <c>mirror</c> + restriction, the <c>mirror</c> override implies a <c>fetch</c> override. + </p> + +<codesample lang="ebuild"> +EAPI=8 + +SRC_URI=" + ${P}.tgz + fetch+https://example.com/${P}-patch-1.tgz + mirror+https://example.com/${P}-fanstuff.tgz" + +RESTRICT="fetch" +</codesample> + + <p> + The following table summarises the new behaviour: + </p> + + <table> + <tr> + <th><c>RESTRICT</c></th> + <th>URI prefix</th> + <th>Fetching</th> + <th>Mirroring</th> + </tr> + <tr> + <ti>(none)</ti> + <ti>(any)</ti> + <ti>allowed</ti> + <ti>allowed</ti> + </tr> + <tr> + <ti rowspan="2">mirror</ti> + <ti>(none) / fetch+</ti> + <ti>allowed</ti> + <ti>prohibited</ti> + </tr> + <tr> + <ti>mirror+</ti> + <ti>allowed</ti> + <ti>allowed</ti> + </tr> + <tr> + <ti rowspan="3">fetch</ti> + <ti>(none)</ti> + <ti>prohibited</ti> + <ti>prohibited</ti> + </tr> + <tr> + <ti>fetch+</ti> + <ti>allowed</ti> + <ti>prohibited</ti> + </tr> + <tr> + <ti>mirror+</ti> + <ti>allowed</ti> + <ti>allowed</ti> + </tr> + </table> + </dd> + + <dt>Install-time dependencies (<c>IDEPEND</c>)</dt> + <dd> + <p> + The primary use for install-time dependencies is to specify dependencies + that are needed during the <c>pkg_postinst</c> phase and that can be + unmerged afterwards. That's pretty much the same as <c>RDEPEND</c>, except + for the unmerging part <d/> and uninstalling a few tools did not seem a + goal justifying another dependency type. + </p> + + <p> + With cross-compilation support in EAPI 7, a new dependency type focused + on the build host (<c>CBUILD</c>) tools was added <d/> <c>BDEPEND</c>. + Unfortunately, this had missed the important use case of running + executables installed to the target system when cross-compiling. + <c>RDEPEND</c> was no longer a suitable method of pulling in tools for + <c>pkg_postinst</c>; and since <c>BDEPEND</c> is not used when installing + from a binary package, something new was needed. + </p> + + <p> + This is where <c>IDEPEND</c> comes in. It is roughly to <c>RDEPEND</c> what + <c>BDEPEND</c> is to <c>DEPEND</c>. Similarly to <c>BDEPEND</c>, + it specifies packages that must be built for the <c>CBUILD</c> triplet + and installed into <c>BROOT</c> (and therefore queried using + <c>has_version -b</c>). However, similarly to <c>RDEPEND</c>, it is used + when the package is being merged rather than built from source. + It is guaranteed to be satisfied throughout <c>pkg_preinst</c> and + <c>pkg_postinst</c>, and it can be uninstalled afterwards. + </p> + +<codesample lang="ebuild"> +EAPI=8 + +inherit xdg-utils + +IDEPEND="dev-util/desktop-file-utils" + +pkg_postinst() { + xdg_desktop_database_update +} + +pkg_postrm() { + xdg_desktop_database_update +} +</codesample> + + <p> + In the example provided above, the ebuild needs to be update the icon cache + upon being installed or uninstalled. By placing the respective tool in + <c>IDEPEND</c>, the ebuild requests it to be available at the time of + <c>pkg_postinst</c>. When cross-compiling, the tool will be built for + <c>CBUILD</c> and therefore directly executable by the ebuild. + </p> + + <p> + The dependency types table for EAPI 8 is presented below. + </p> + + <table> + <tr> + <th>Dependency type</th> + <th>BDEPEND</th> + <th>IDEPEND</th> + <th>DEPEND</th> + <th>RDEPEND</th> + <th>PDEPEND</th> + </tr> + <tr> + <th>Present at</th> + <ti>build</ti> + <ti>install</ti> + <ti>build</ti> + <ti>install</ti> + <ti>n/a</ti> + </tr> + <tr> + <th>Binary compatible with</th> + <ti colspan="2">CBUILD</ti> + <ti colspan="3">CHOST</ti> + </tr> + <tr> + <th>Base unprefixed path</th> + <ti colspan="2"><c>/</c></ti> + <ti>SYSROOT</ti> + <ti colspan="2">ROOT</ti> + </tr> + <tr> + <th>Relevant offset-prefix</th> + <ti colspan="2">BROOT</ti> + <ti>EPREFIX (unless SYSROOT != ROOT)</ti> + <ti colspan="2">EPREFIX</ti> + </tr> + <tr> + <th>Path combined with prefix</th> + <ti colspan="2">BROOT</ti> + <ti>ESYSROOT</ti> + <ti colspan="2">EROOT</ti> + </tr> + <tr> + <th>PM query command option</th> + <ti colspan="2"><c>-b</c></ti> + <ti><c>-d</c></ti> + <ti colspan="2"><c>-r</c></ti> + </tr> + </table> + </dd> + + <dt> + <c>PROPERTIES</c> and <c>RESTRICT</c> are now accumulated across eclasses + </dt> + <dd> + <p> + Up to EAPI 7, <c>PROPERTIES</c> and <c>RESTRICT</c> were treated like + regular Bash variables when sourcing eclasses. This meant that if an eclass + or an ebuild wanted to modify them, they had to explicitly append to them, + e.g. via <c>+=</c>. This was inconsistent with how some other variables + (but not all) were handled, and confusing to developers. For example, + consider the following snippet: + </p> + +<codesample lang="ebuild"> +EAPI=7 + +inherit git-r3 + +PROPERTIES+=" live" +</codesample> + + <p> + Note how you needed to append to <c>PROPERTIES</c> set by git-r3 eclass, + otherwise the ebuild would have overwritten it. In EAPI 8, you can finally + do the following instead: + </p> + +<codesample lang="ebuild"> +EAPI=8 + +inherit git-r3 + +PROPERTIES="live" +</codesample> + + <p> + Now the complete list of metadata variables accumulated across eclasses + and ebuilds includes: <c>IUSE</c>, <c>REQUIRED_USE</c>, <c>*DEPEND</c>, + <c>PROPERTIES</c>, <c>RESTRICT</c>. Variables that are not treated this way + are: <c>EAPI</c>, <c>HOMEPAGE</c>, <c>SRC_URI</c>, <c>LICENSE</c>, + <c>KEYWORDS</c>. <c>EAPI</c> and <c>KEYWORDS</c> are not supposed to be set + in eclasses; as for the others, there appears to be a valid use case for + eclasses providing default values and the ebuilds being able to override + them. + </p> + </dd> +</dl> + +</body> +</subsection> +<subsection> +<title>EAPI 8 phase functions</title> +<body> + +<dl> + <dt><c>pkg_*</c> phases now run in a dedicated empty directory</dt> + <dd> + <p> + Before EAPI 8, the initial working directory was specified for <c>src_*</c> + phases only. For other phases (i.e. <c>pkg_*</c> phases), ebuilds were not + supposed to assume any particular directory. In EAPI 8, these phases are + guaranteed to be started in a dedicated empty directory. + </p> + + <p> + The idea of using an empty directory is pretty simple <d/> if there are no + files in it, the risk of unexpected and hard to predict interactions of + tools with their current working directory is minimized. + </p> + </dd> + + <dt> + <c>PATCHES</c> no longer permits options + </dt> + <dd> + <p> + The <c>eapply</c> invocation in the default <c>src_prepare</c> + implementation has been changed to: + </p> + +<codesample lang="ebuild"> +eapply -- "${PATCHES[@]}" +</codesample> + + <p> + This ensures that all items in the <c>PATCHES</c> variable are treated + as path names. As a side effect, it is no longer possible to specify + <c>patch</c> options via the <c>PATCHES</c> variable. Such hacks were never + used in the Gentoo repository but they have been spotted in + user-contributed ebuilds. The following will no longer work: + </p> + +<codesample lang="ebuild"> +PATCHES=( -p0 "${FILESDIR}"/${P}-foo.patch ) +</codesample> + + <p> + Instead, you will need to invoke <c>eapply</c> explicitly, see the example + below. Alternatively, rebase the patch level. + </p> + +<codesample lang="ebuild"> +src_prepare() { + eapply -p0 "${FILESDIR}"/${P}-foo.patch + eapply_user +} +</codesample> + + </dd> +</dl> </body> +</subsection> +<subsection> +<title>EAPI 8 commands</title> +<body> + +<dl> + <dt>New econf-passed options</dt> + <dd> + <p> + The <c>econf</c> helper has been modified to pass two more options to + the configure script if the <c>--help</c> text indicates that they are + supported. These are: + </p> + + <ul> + <li><c>--datarootdir="${EPREFIX}"/usr/share</c></li> + <li><c>--disable-static</c></li> + </ul> + + <p> + The former option defines the base directory that is used to determine + locations for system/desktop-specific data files, e.g. .desktop files and + various kinds of documentation. This is necessary for ebuilds that override + <c>--prefix</c>, as the default path is relative to it. + </p> + + <p> + The latter option disables building static libraries by default. This is + part of the ongoing effort to disable unconditional install of static + libraries + (<uri link="https://projects.gentoo.org/qa/policy-guide/installed-files.html#pg0302"> + Gentoo Policy Guide, Installation of static libraries</uri>). + </p> + </dd> + + <dt><c>dosym -r</c> to create relative symlinks</dt> + <dd> + <p> + Relative symlink targets tend to be more reliable. Consider the two + following examples: + </p> + +<codesample lang="ebuild"> +dosym "${EPREFIX}"/usr/lib/frobnicate/frobnicate /usr/bin/frobnicate +dosym ../lib/frobnicate/frobnicate /usr/bin/frobnicate +</codesample> + + <p> + The first line creates a symlink using an absolute path. The problem with + that is if you mount your Gentoo system in a subdirectory of your root + filesystem (e.g. for recovery), the symlink will point at the wrong + location. Using relative symlinks (as demonstrated on the second line) + guarantees that the symlink will work independently of where the filesystem + is mounted. + </p> + + <p> + There is also fact that you need to explicitly prepend <c>${EPREFIX}</c> + to the absolute paths passed as the first argument of <c>dosym</c>. Using + a relative target avoids the problem altogether and makes it less likely to + forget about the prefix. + </p> + + <p> + However, in some instances, determining the relative path could be hard or + inconvenient. This is especially the case if one (or both) of the paths + comes from an external tool. To make it easier, EAPI 8 adds a new <c>-r</c> + option that makes <c>dosym</c> create a relative symlink to the specified + path (similarly to <c>ln -r</c>): + </p> + +<codesample lang="ebuild"> +dosym -r /usr/lib/frobnicate/frobnicate /usr/bin/frobnicate +</codesample> + + <p> + Note that in this case, you do not pass <c>${EPREFIX}</c>. The helper + determines the <e>logical</e> relative path to the first argument and + creates the appropriate relative symlink. It is very important here to + understand that this function does not handle physical paths, i.e. it will + work only if there are no directory symlinks along the way that would + result in <c>..</c> resolving to a different path. For example, the + following will not work: + </p> + +<codesample lang="ebuild"> +dosym bar/foo /usr/lib/foo +dosym -r /usr/lib/zomg /usr/lib/foo/zomg +</codesample> + + <p> + The logical path from <c>/usr/lib/foo/zomg</c> to <c>/usr/lib/zomg</c> is + <c>../zomg</c>. However, since <c>/usr/lib/foo</c> is actually a symlink to + <c>/usr/lib/bar/foo</c>, <c>/usr/lib/foo/..</c> resolves to + <c>/usr/lib/bar</c>. If you need to account for such directory symlinks, + you need to specify the correct path explicitly: + </p> + +<codesample lang="ebuild"> +dosym bar/foo /usr/lib/foo +dosym ../../zomg /usr/lib/foo/zomg +</codesample> + + </dd> + + <dt> + <c>insopts</c> and <c>exeopts</c> now apply to <c>doins</c> + and <c>doexe</c> only + </dt> + <dd> + <p> + In previous EAPIs, there was an inconsistency in how <c>insopts</c> and + <c>exeopts</c> applied to various helpers. In particular, the majority of + helpers (e.g. <c>dobin</c>, <c>dodoc</c> and so on) ignored the options + specified via these helpers but a few did not. + </p> + + <p> + EAPI 8 changes the behaviour of the following helpers that used to respect + <c>insopts</c> or <c>exeopts</c>: + </p> + + <ul> + <li><c>doconfd</c></li> + <li><c>doenvd</c></li> + <li><c>doheader</c></li> + <li><c>doinitd</c></li> + </ul> + + <p> + In EAPI 8, they always use the default options. As a result, <c>insopts</c> + now only affects <c>doins</c>/<c>newins</c>, and <c>exeopts</c> only + affects <c>doexe</c>/<c>newexe</c>. Furthermore, <c>diropts</c> does not + affect the directories implicitly created by these helpers. + </p> + </dd> + + <dt><c>usev</c> now accepts a second argument</dt> + <dd> + <p> + The <c>usev</c> helper was introduced to provide the historical Portage + behaviour of outputting the USE flag name on match. In EAPI 8, it has been + extended, in order to provide an alternative to three-argument <c>usex</c> + with an empty third argument (the two-argument <c>usex</c> variant uses a + default of <c>no</c> for the false branch). + </p> + + <p> + In other words, the following two calls are now equivalent: + </p> + +<codesample lang="ebuild"> +$(usex foo --enable-foo '') +$(usev foo --enable-foo) +</codesample> + + <p> + This is particularly useful with custom build systems that accept + individual <c>--enable</c> or <c>--disable</c> options but not their + counterparts. + </p> + + <p> + As a result, <c>usev</c> and <c>usex</c> can now be used to achieve all the + common (and less common) output needs as summarized in the following table. + </p> + + <table> + <tr> + <th>Variant</th> + <th>True</th> + <th>False</th> + </tr> + <tr> + <ti>usev <e>flag</e></ti> + <ti><e>flag</e></ti> + <ti></ti> + </tr> + <tr> + <ti>usev <e>flag</e> <e>true</e></ti> + <ti><e>true</e></ti> + <ti></ti> + </tr> + <tr> + <ti>usex <e>flag</e></ti> + <ti><c>yes</c></ti> + <ti><c>no</c></ti> + </tr> + <tr> + <ti>usex <e>flag</e> <e>true</e></ti> + <ti><e>true</e></ti> + <ti><c>no</c></ti> + </tr> + <tr> + <ti>usex <e>flag</e> <e>true</e> <e>false</e></ti> + <ti><e>true</e></ti> + <ti><e>false</e></ti> + </tr> + </table> + </dd> + + <dt><c>hasq</c>, <c>hasv</c> and <c>useq</c> functions have been banned</dt> + <dd> + <p> + In its early days, the <c>use</c> helper would print the USE flag name + if it matched, in addition to its boolean exit status. Later, a quiet + <c>useq</c> and a verbose <c>usev</c> helper were added, and <c>use</c> was + made quiet by default. The same changes were applied to <c>has</c>. + </p> + + <p> + Fast forward to EAPI 7, there are still three variants of <c>use</c> + and three variants of <c>has</c>. The base variant that is quiet, the + <c>useq</c>/<c>hasq</c> variant that is equivalent to the base variant, + and the verbose <c>usev</c>/<c>hasv</c> variant. + </p> + + <p> + Obviously, adding a second argument to <c>hasv</c> was not possible, so its + behaviour would have become inconsistent with <c>usev</c> in EAPI 8. Since + <c>hasv</c> was not used in the Gentoo repository, it has been removed, + along with <c>hasq</c> and <c>useq</c> which were considered deprecated + since 2011. + </p> + </dd> + + <dt>unpack removes support for 7-Zip, LHA and RAR formats</dt> + <dd> + <p> + Support for the least commonly used archive formats from <c>unpack</c> has + been removed: + </p> + + <ul> + <li>7-Zip (.7z)</li> + <li>LHA (.lha, .lzh)</li> + <li>RAR (.rar)</li> + </ul> + + <p> + Packages using these format for distfiles must now unpack them manually. + Using <c>unpacker.eclass</c> is recommended for this. + </p> + </dd> +</dl> + +</body> +</subsection> +</section> </chapter> </guide> diff --git a/ebuild-writing/ebuild-maintenance/text.xml b/ebuild-writing/ebuild-maintenance/text.xml deleted file mode 100644 index 4fa3a8b..0000000 --- a/ebuild-writing/ebuild-maintenance/text.xml +++ /dev/null @@ -1,487 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/ebuild-maintenance/"> -<chapter> -<title>Ebuild Maintenance</title> - -<body> -<p> -This guide aims to explain common everyday ebuild maintenance -routines, as well as other rarer maintenance routines which -developers may not be familiar with. -</p> - -<section> -<title>Adding a new ebuild</title> -<body> - -<subsection> -<title>What (not) to put in the Portage tree</title> -<body> - -<p> -Before writing a new ebuild, check -<uri link="https://bugs.gentoo.org/">bugs.gentoo.org</uri> -to see if an ebuild has already been written for the package, but has not yet -been added to the Portage tree. Go to <uri -link="https://bugs.gentoo.org/">bugs.gentoo.org</uri>, choose query and select -Advanced Search; as product select <e>Gentoo Linux</e>, as component select -<e>ebuilds</e>. In the search field put the name of the ebuild and as status -select NEW, ASSIGNED, REOPENED and RESOLVED (RESOLVED is important), then -submit the query. For you lazy people, click <uri -link="https://bugs.gentoo.org/query.cgi?product=Gentoo%20Linux&component=Ebuilds&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=RESOLVED">here</uri>. -</p> - -<p> -In general, the Portage tree should only be used for storing -<path>.ebuild</path> files, as well as any relatively small companion -files, such as patches or sample configuration files. These types of -files should be placed in the <path>/usr/portage/mycat/mypkg/files</path> -directory to keep the main <path>mycat/mypkg</path> directory uncluttered. -Exceptions to this rule are for larger patch files (we recommend this for patches -above 20KB) which should be distributed as tarballs via the -<uri link="::general-concepts/mirrors/#suitable-download-hosts">Gentoo mirror system</uri> -so that people do not waste excessive amounts of bandwidth and hard drive -space. Also, you should not add binary (non-ASCII) files to the -Portage CVS tree. If you need to do this in another CVS tree, for -example, if you need to add a small PNG graphic for whatever reason, -be sure to add it to CVS by using the <c>-kb</c> option, like so: -</p> - -<pre caption="Adding binary files to CVS"> -# <i>cvs add -kb myphoto.png</i> -</pre> - -<p> -The <c>-kb</c> option tells CVS that <path>myphoto.png</path> is a binary -file and should be treated specially. For example, merging the -differences between two different versions of this file should not be -allowed to happen, for obvious reasons. Also, speaking of merging -changes, any patches you add to Portage should generally <e>not</e> be -compressed. This will allow CVS to merge changes and correctly inform -developers of conflicts. -</p> - -<p> -Remember, the packages that you commit must be <e>ready</e> <e>out of the -box</e> for end users when committed as stable. Make sure that you have a good -set of default settings that will satisfy the majority of systems and -users that will use your package. If your package is broken, and you are -not sure how to get it to work, check some other distributions that have -done their own versions of the package. You can check -<uri link="http://cvs.mandriva.com/cgi-bin/viewvc.cgi/SPECS/">Mandriva</uri> -or <uri link="http://www.debian.org/distrib/packages">Debian</uri> or -<uri link="http://cvs.fedora.redhat.com/">Fedora</uri> for some -examples. -</p> - -<p> -When committing to CVS, all developers should use <c>repoman commit</c> -instead of <c>cvs commit</c> to submit their ebuilds. Before committing, -please run <c>repoman full</c> to make sure you didn't forget something. -</p> - -</body> -</subsection> - -<subsection> -<title>Initial Architecture Keywords</title> -<body> -<p> -When adding a new ebuild, you should only include <c>KEYWORDS</c> for -architectures on which you have actually tested the ebuild, confirming -that it works as it should and that <c>USE</c> flags are properly -honoured in the resulting package which would be installed. If -possible, you should give the actual library or application thorough -testing as well, since you would be responsible for any breakages for -your architecture(s). Minimal testing such as checking that the -application starts up without any errors should always be performed. -</p> - -<p> -If you are adding a user-submitted ebuild, do not assume that the -submitter has done testing on various architectures: often, <c>KEYWORDS</c> -are cloned across packages or generated from documentation in the -source packages, which does not signify that the package does indeed -work on those architectures. -</p> - -</body> -</subsection> - -<subsection> -<title>CVS Commit Policy</title> -<body> - -<ul> -<li>Always run <c>repoman scan</c> before you commit.</li> -<li>Please run <c>repoman full</c> before you commit.</li> -<li>Always test that <path>package.mask</path> is okay by doing -<c>emerge --pretend mypkg</c> before you commit and check -that it doesn't contain any conflicts.</li> -<li>Always update the <path>ChangeLog</path> before you commit.</li> -<li>Always commit the updated <path>package.mask</path> before -the updated package, in case conflicts occur while you commit -<path>package.mask</path>.</li> -<li>Always do atomic commits; if you commit a package with a new license, -or that is masked, then first commit the revised <path>package.mask</path> and/or license, -then commit the ebuild, <path>ChangeLog</path>, patches -and <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> all in <b>one</b> go -to avoid breaking users' installations.</li> -</ul> - -</body> -</subsection> - -<subsection> -<title>The files Directory</title> -<body> - -<p> -As noted earlier, under each package subdirectory is -a <path>files/</path> directory. Any patches, configuration files, or -other ancillary files your package might require should be added to -this directory; any files bigger than 20KB-or-so should go to the -mirrors to lower the amount of (unneeded) files our users have to -download. You may want to consider naming patches you create yourself -just to get your package to build with a version-specific name, such -as <path>mypkg-1.0-gentoo.diff</path>, or more -simply, <path>1.0-gentoo.diff</path>. Also note that the -<path>gentoo</path> extension informs people that this patch was created -by us, the Gentoo Linux developers, rather than having been grabbed from a -mailing list or somewhere else. Again, you should not compress these -patches because CVS does not play well with binary files. -</p> - -<p> -Consider prefixing or suffixing (such as <path>mypkg-1.0</path>) every file -you put into the <path>files/</path> directory, so that the files used for -each individual version on an ebuild are distinguishable from one another, and -so that the changes between different revisions are visible. This is generally -a really good idea :). You may want to use a different suffix if you wish to -convey more meaning with the patch name. -</p> - -<p> -If you have many files that should go into the <path>files/</path> directory, -consider creating subdirectories such as <path>files/1.0/</path> and putting the -relevant files in the appropriate subdirectory. If you use this method, -you do not need to add version information to the names of the files, -which is often more convenient. -</p> - -</body> -</subsection> - -</body> -</section> - -<section> -<title>Touching other developers ebuilds</title> -<body> -<p>Usually you don't just change other developers ebuilds without permission unless you know that developer does not mind or if you are part of the herd involved in maintenance (this information can typically be found in metadata.xml). Start with filing a bug or trying to catch them on IRC or via email. Sometimes you cannot reach them, or there is no response to your bug. It's a good idea to consult other developers on how to handle the situation, especially if it's a critical issue that needs to be handled ASAP. Otherwise a soft limit of 2 to 4 weeks depending on the severity of the bug is an acceptable time frame before you go ahead and fix it yourself.</p> -<important> Common sense dictates to us that toolchain/base-system/core packages and eclasses or anything else which is delicate (e.g. glibc) or widely used (e.g. gtk+) should usually be left to those maintainers. If in doubt, don't touch it.</important> -</body> -</section> - -<section> -<title>Stabilizing ebuilds</title> -<body> - -<p> -Only architecture maintainers for a given architecture should mark packages as -stable on that architecture. The maintainer of the package should always be -contacted just in case there are reasons not to do so. The exception to this -is if you are part of an architecture team, in which case you may mark the -package stable for that architecture. If you are not part of an architecture -team, you should consult the guidelines below; if the architecture you are -looking for is not listed then please consult the relevant lead. -</p> - -<p> -You should <e>never</e> stabilize packages on -architectures for which you cannot test and instead you should file a bug to -the relevant architecture team, such as <mail link="sparc@gentoo.org"> -sparc@gentoo.org</mail> asking them to stabilize the -ebuild. Alternatively, you may be able to find Gentoo developers on -IRC who could help you with your request. -</p> - -<p> -It is best to not use <mail link="arch-maintainers@gentoo.org"> -arch-maintainers@gentoo.org</mail>, adding architecture teams onto a -bug's CC list individually instead. That way teams can remove -themselves from the list when they are done, giving a clear indication -of which teams still have to stabilize a package. -</p> - -</body> -</section> - -<section> -<title>Stabilization rules</title> -<body> - -<p> -SPARC: You must have prior permission from the arch lead. Usually we expect -you to be on the sparc alias for QA reasons, although other arrangements -can be made if you will only be working with a small group of packages. -</p> - -<p> -ALPHA: Maintainers may keyword their own packages but are reminded to inform -the Alpha team if they can help out with testing and keywording packages so -the team can keep an eye out for possible keywording mistakes. -</p> - -<p> -Exotic architectures (like alpha, ia64, sparc, hppa, ppc*) are short on manpower, so it's best if you avoid opening stabilization bugs for them unless it is absolutely necessary (eg, a reverse dependency for your package). More about keywording policies can be found in the <uri link="::keywording">keywording</uri> section. -</p> -<p> -Some architectures (like m68k, mips, s390, sh) do not maintain a stable keyword. So there is no use in marking a package stable for one of these architectures. -</p> -</body> -</section> - -<section> -<title>Upgrading ebuilds</title> -<body> - -<p> -New ebuilds should rarely go in with "<c>arch</c>" keywords and even if they do -not, the package <e>must</e> be tested on any architectures listed in the -<c>KEYWORDS</c> variable of the new ebuild. -</p> - -<p> -Exceptions to the no "<c>arch</c>" rule are major bug fixes, or -security fixes. If the previous version of the ebuild -contains <c>KEYWORDS</c> which you cannot test for, you should -downgrade them: turn any "<c>arch</c>" keyword to "<c>~arch</c>". If you -think that your package may not work at all even on "<c>~arch</c>" -then it is best to leave the keyword out and request testing from the -relevant team: if you are to do this, you must file a bug to the team -in question. -</p> - -<p> -If a new version introduces new dependencies which are not available -on some architectures, then you should file a bug or ask on IRC before -you upgrade the package. If you really need to get the ebuild added in -a hurry, for example, for a security fix, then you should drop -any <c>KEYWORDS</c> which are causing problems and CC the relevant -architectures on the bug - you should file a new bug to the -architecture in question regarding this if no bug is already -available. -</p> - -<p> -If there are no new dependencies, do not remove keywords if your -commit fails with repoman - please try a full <c>cvs update</c> and if -you still have problems, then commit with <c>repoman -I</c> and file a -bug to the broken architecture, noting it in your CVS commit message. -</p> - -<warn> -When committing, make sure that you reference any bugs in the -ChangeLog as well as the CVS message. Failing to do so is considered -to be in very poor taste and may result in disciplinary action. -</warn> - -</body> -</section> - -<section> -<title>Moving ebuilds</title> -<body> - -<p> -Moving ebuilds is a two-step process: -</p> - -<p> -Firstly, you need to move the ebuild in CVS. To do this, you should -copy the ebuild to its new location and commit that as you would with -a <uri link="#adding-a-new-ebuild">new ebuild</uri>. -</p> - -<p> -After this, you should change any ebuilds which <c>DEPEND</c> on the -old ebuild to depend on the new one. After this, should add an entry to the -latest file in <path>profiles/updates/</path> in the Portage tree in the in -the following format: -</p> - -<pre caption="Adding an entry to updates"> -move net-misc/fwbuilder net-firewall/fwbuilder -</pre> - -<p> -This example would transparently move <path>net-misc/fwbuilder</path> to -<path>net-firewall/fwbuilder</path> if users have it installed. This -way, users would now automatically receive updates -for <path>net-firewall/fwbuilder</path> when they are available. -</p> - -<p> -Once this step is concluded, you are allowed to remove the old package. -Simply issue a <c>cvs remove -Rf $PN</c> in the package category and commit -the changes afterwards with a meaningful commit message. Don't forget to update -entries in files such as profiles/package.mask to reflect the new category. Finally -remember to change the title to open bugs related to this package if needed. -</p> - -<pre caption="Removing a package"> -net-misc # cvs rm -Rf fwbuilder -cvs remove: use `cvs commit' to remove these files permanently -net-misc # cvs ci -m "Moving net-misc/fwbuilder to net-firewall/fwbuilder." -</pre> - -<note> -CVS cannot destroy directories: it will simply not re-create them if -they are blank, providing you use CVS with the <c>-P</c> flag. -</note> - -</body> -</section> - -<section> -<title>Changing ebuild's SLOT</title> -<body> -<p> -The process for changing the ebuild's SLOT is very similar to the previous process. -Besides changing the SLOT in the ebuild file, you also need to create a new entry -in <path>profiles/updates/</path> in the Portage tree in the following format: -</p> - -<pre caption="Adding an entry to updates"> -slotmove app-text/gtkspell 0 2 -</pre> - -<p>Make sure that you have fixed all the reverse dependencies and that you have -updated every file in <path>profiles/</path> directory that happens to contain an -entry which may be affected by your change. -</p> - -</body> -</section> - -<section> -<title>Removing ebuilds</title> -<body> - -<p> -When removing an ebuild make sure that no dependencies in Portage are broken -due to the removal - additionally, your CVS commit message should explain -clearly why the ebuild is being removed from CVS. -</p> - -<p> -If you need to remove ebuilds, make sure you do not accidentally remove -the newest/only stable ebuild for any architecture. If you would like to -get a newer version marked stable, then please file a bug or ask on IRC. -</p> - -<p> -You should also not cause an unnecessary downgrade for any "<c>~arch</c>" -when removing ebuilds - instead, it is best to get the newest version -marked "<c>~arch</c>" first and then remove redundant versions of the ebuild. -</p> - -</body> -</section> - -<section> -<title>Removing a package</title> -<body> - -<p> -When removing packages follow these steps: -</p> - -<ol> - <li>Make sure that no dependencies in Portage are broken due to the removal</li> - <li>Send last rites to gentoo-dev-announce and gentoo-dev</li> - <li>Mask the package</li> - <li>Wait 30 days (or more)</li> - <li>Remove from CVS unless the reason for removal has been fixed</li> - <li>Remove package.mask entry</li> - <li>Close open bugs as WONTFIX</li> -</ol> - -<p> -In order to remove a package completely from CVS, delete any files from the -directory and commit this, CVS will take care of removing empty directories -itself. -</p> - -<pre caption="Removing a package from CVS"><comment>#</comment> <keyword>cd</keyword> app-admin -<comment>#</comment> <keyword>cvs</keyword> rm -Rf scotty -<comment>#</comment> <keyword>cvs</keyword> ci -m "app-admin/scotty removal (pending 21st July 2006), see #77501 for reference." scotty</pre> - -</body> -</section> - -<section> -<title>Conflicting files</title> -<body> - -<p> -When you encounter a package that is trying to install files that are -already provided by another package (detectable with -<c>FEATURES=collision-protect</c> for example) you have to fix this -situation before you can commit the ebuild or, if you encounter this -with an existing package, file a bug about that package (see below for -a few exceptions). The reason file conflicts are critical is because -if "foo" provides the file <path>/usr/bin/example</path> and "bar" is -going to overwrite it, and later "bar" is unmerged, Portage will remove -<path>/usr/bin/example</path> and it is therefore likely it will break -"foo". -</p> - -<p> -The most obvious fix is to add a blocking dependency to both packages -that want to install that file, so they can't be installed at the same -time. But unless there are also other reasons for those packages to -block each other you should avoid this if possible and rather fix the -package, which could include one or more of the following steps: -</p> - -<ul> - <li>Make "foo" (R)DEPEND on "bar" and not install the conflicting - file.</li> - <li>Remove conflicting files from "foo" in <c>src_install</c> - or <c>pkg_preinst</c>.</li> - <li>Move conflicting files into a new subpackage and make "foo" and - "bar" both (R)DEPEND on that package.</li> - <li>Change the location where "foo" or "bar" installs conflicting - files.</li> -</ul> - -<p> -In some cases conflicting files can't be really fixed or aren't -critical, currently known exceptions are Perl module manpages -(overwriting the ones from Perl itself) and <c>CONFIG_PROTECT</c>'ed -files (which should still be fixed, but aren't critical as Portage -won't overwrite them). -</p> - -</body> -</section> - -<section> -<title>Homepage unavailable</title> -<body> - -<p> -If the <c>HOMEPAGE</c> of your package seems to be unavailable or it -never existed at all, please set the HOMEPAGE variable in every ebuild -to <uri link="https://wiki.gentoo.org/wiki/No_homepage"> -https://wiki.gentoo.org/wiki/No_homepage</uri> -</p> - -</body> -</section> - -</body> -</chapter> -</guide> diff --git a/ebuild-writing/error-handling/text.xml b/ebuild-writing/error-handling/text.xml index 40b8b5b..f8171f5 100644 --- a/ebuild-writing/error-handling/text.xml +++ b/ebuild-writing/error-handling/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/error-handling/"> <chapter> <title>Error Handling</title> @@ -13,7 +13,7 @@ Decent error handling is important because: <ul> <li> - Errors must be detected <e>before</e> portage tries to install a broken or + Errors must be detected <e>before</e> Portage tries to install a broken or incomplete package onto the live filesystem. If build failures aren't caught, a working package could be unmerged and replaced with nothing. </li> @@ -47,21 +47,20 @@ function can die in multiple places. </p> <p> -Some portage-provided functions will automatically die upon failure. Others will -not. It is for example safe to omit the <c>|| die</c> after a call to <c>epatch</c>, -but not <c>emake</c>. The reason is that external binaries are not able to call -die that is a bash function. You can see what commands are external binaries -with <c>ls /usr/lib*/portage/bin/ebuild-helpers</c>. In <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri> all ebuild-helpers automatically die upon failure. +Ebuild helpers automatically die on failure. Some eclass-provided functions +will automatically die upon failure, others will not. Developers should check +the <uri link="::eclass-reference/">eclass reference</uri> when in doubt. </p> <p> Sometimes displaying additional error information beforehand can be useful. Use -<c>eerror</c> to do this. See <uri link="::ebuild-writing/messages"/>. +<c>eerror</c> to do this. See <uri link="::ebuild-writing/messages/"/>. </p> -<p> -It's best to use <c>|| die</c> too often than too little. -</p> +<note> +You should use <c>die</c> on almost all external commands in ebuilds. +</note> + </body> </section> @@ -70,7 +69,7 @@ It's best to use <c>|| die</c> too often than too little. <body> <warning> -<c>die</c> <b>will not work in a subshell</b>. +<c>die</c> <b>will not work in a subshell unless you are using EAPI=7 and onwards</b>. </warning> <p> @@ -88,7 +87,7 @@ The correct way to rewrite this is to use an <c>if</c> block: <codesample lang="ebuild"> if [[ -f foorc ]] ; then - update_foorc || die "Couldn't update foorc!" + update_foorc || die "Couldn't update foorc!" fi </codesample> @@ -97,7 +96,7 @@ When using pipes, a subshell is introduced, so the following is unsafe: </p> <codesample lang="ebuild"> -cat list | while read file ; do epatch ${file} ; done +cat list | while read file ; do eapply ${file} ; done </codesample> <p> @@ -106,7 +105,7 @@ avoids this problem: </p> <codesample lang="ebuild"> -while read file ; do epatch ${file} ; done < list +while read file ; do eapply ${file} ; done < list </codesample> </body> @@ -119,7 +118,7 @@ while read file ; do epatch ${file} ; done < list <p> When using pipes, simple conditionals and tests upon <c>$?</c> will not correctly detect errors occurring in anything except the final command in the chain. To get -around this, <c>bash</c> provides the <c>$PIPESTATUS</c> variable, and portage +around this, <c>bash</c> provides the <c>$PIPESTATUS</c> variable, and Portage provides the <c>assert</c> function to check this variable. </p> @@ -136,5 +135,30 @@ time, <c>assert</c> is enough. </body> </section> +<section> +<title>The <c>nonfatal</c> Command</title> +<body> + +<p> +If a non-zero exit status from an ebuild helper function is expected, you may +call it under the <c>nonfatal</c> function. Instead of dying on failure, +the command will then return non-zero exit status, as in the following example: +</p> + +<codesample lang="ebuild"> +src_test() { + if ! nonfatal emake check ; then + local a + eerror "Tests failed. Looking for files to add to your bug report..." + while IFS='' read -r -d $'\0' a ; do + eerror " ${a}" + done < <(find "${S}" -type f -name '*.log' -print0) + die "Make check failed" + fi +} +</codesample> + +</body> +</section> </chapter> </guide> diff --git a/ebuild-writing/file-format/text.xml b/ebuild-writing/file-format/text.xml index de2380a..3772554 100644 --- a/ebuild-writing/file-format/text.xml +++ b/ebuild-writing/file-format/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/file-format/"> <chapter> <title>Ebuild File Format</title> @@ -25,22 +25,29 @@ discouraged, but technically valid. </p> <note> -This is the same as <uri link="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_276"> -IEEE1003.1-2004-3.276</uri>, with the exception of the period character and with the -addition of the plus character to keep GTK+ and friends happy. +This is the same as +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282"> +IEEE Std 1003.1-2017, section 3.282 (Portable Filename Character Set)</uri>, +with the exception of the period character and with the addition of the plus +character to keep GTK+ and friends happy. </note> <p> +The name must not begin with a hyphen or a plus sign, and must not end +in a hyphen followed by anything that could be mistaken for a version. +</p> + +<p> The version section is more complicated. It consists of one or more numbers separated by full stop (or period, or dot, or decimal point) characters (eg <c>1.2.3</c>, <c>20050108</c>). The final number may have a single letter following it (e.g. <c>1.2b</c>). This letter should not be used to indicate 'beta' status <d/> -portage treats <c>1.2b</c> as being a later version than <c>1.2</c> or <c>1.2a</c>. +Portage treats <c>1.2b</c> as being a later version than <c>1.2</c> or <c>1.2a</c>. </p> <p> There can be a suffix to version indicating the kind of release. In the following table, -what portage considers to be the 'lowest' version comes first. +what Portage considers to be the 'lowest' version comes first. </p> <table> @@ -69,18 +76,19 @@ what portage considers to be the 'lowest' version comes first. <ti>Normal release</ti> </tr> <tr> - <ti>_p</ti> + <ti><c>_p</c></ti> <ti>Patch release</ti> </tr> </table> <p> -Any of these suffixes may be followed by a non-zero positive integer. +Any of these suffixes may be followed by an unsigned integer. </p> <p> These suffixes can be chained together and will be processed iteratively. To give some examples (the following list is from lowest version to highest): +</p> <ul> <li>foo-1.0.0_alpha_pre</li> @@ -88,19 +96,19 @@ give some examples (the following list is from lowest version to highest): <li>foo-1.0.0_beta_pre</li> <li>foo-1.0.0_beta_p1</li> </ul> -</p> <p> No integer part of the version may be longer than 18 digits. </p> <p> -Finally, version may have a Gentoo revision number in the form <c>-r1</c>. The initial -Gentoo version should have no revision suffix, the first revision should be -<c>-r1</c>, the second <c>-r2</c> and so on. See <uri link="::general-concepts/ebuild-revisions"/>. -Revision numbers are distinguished from patch releases by revision bumps being -changes by Gentoo developers, while patch releases are new releases by upstream (with the exception -of snapshots, see below). +Finally, version may have a Gentoo revision number in the form <c>-r1</c>. +The initial Gentoo version should have no revision suffix, the first revision +should be <c>-r1</c>, the second <c>-r2</c> and so on. +See <uri link="::general-concepts/ebuild-revisions/"/>. Revision numbers are +distinguished from patch releases by revision bumps being changes by Gentoo +developers, while patch releases are new releases by upstream (with the +exception of snapshots, see below). </p> <p> @@ -108,14 +116,65 @@ Overall, this gives us a filename like <c>libfoo-1.2.5b_pre5-r2.ebuild</c>. </p> <p> -When packaging a snapshot of a source repository, there are two commonly used formats. The first -treats the snapshot as a patch to the previous version, and so the ebuild version is in the format -$(last-released-version)_pYYYYMMDD. Alternatively, the snapshot may be treated as a pre-release to -an upcoming version, usually used when a release is anticipated but not out yet. The format for this -is $(upcoming-version)_preYYYYMMDD. +The <uri link ="::ebuild-writing/variables/#Version and Name Formatting Issues"> +EAPI 7 version commands</uri> may be used to manipulate and extract +ebuild version components. +</p> + +<p> +The formal specification of version +<uri link="https://projects.gentoo.org/pms/8/pms.html#x1-250003.2"> +format</uri> and the comparison +<uri link="https://projects.gentoo.org/pms/8/pms.html#x1-260003.3"> +algorithm</uri> can be found in PMS. </p> </body> + +<subsection> +<title>Snapshots and live ebuilds</title> +<body> + +<p> +When packaging a snapshot of a source repository, there are two commonly used +formats. The first treats the snapshot as a patch to the previous version, and +so the ebuild version is in the format $(last-released-version)_pYYYYMMDD. +Alternatively, the snapshot may be treated as a pre-release to an upcoming +version, usually used when a release is anticipated but not out yet. The format +for this is $(upcoming-version)_preYYYYMMDD. +</p> + +<p> +The policy for so-called <e>live</e> ebuilds +(see <uri link="::ebuild-writing/functions/src_unpack/#src_unpack Actions"/>) +is to use <c>9999</c> as the version (or as the last version component). For +packages with more than 4 digits e.g. YYYYMMDD format, <c>99999999</c> is an +acceptable alternative. +</p> + +</body> +</subsection> + +<subsection> +<title>Binary packages</title> +<body> + +<p> +Gentoo usually builds its packages from source. Exceptionally, a binary package +can be provided instead (e.g., if upstream does not provide a source). +Such packages should still follow normal naming conventions and do not need any +special suffix. +</p> + +<p> +If a binary package is provided in addition to its open-source based +equivalent, the name of the former should be suffixed with <c>-bin</c> +if necessary for distinction. Examples are packages that are heavy on resources +like CPU time or memory when being built from source. +</p> + +</body> +</subsection> </section> <section> @@ -123,18 +182,25 @@ is $(upcoming-version)_preYYYYMMDD. <body> <p> -All ebuilds committed to the tree should have a three line header immediately at -the start indicating copyright. This must be an exact copy of the contents of -<c>$(portageq portdir)/header.txt</c>. Ensure that the <c>$Header: $</c> line is not -modified manually <d/> CVS will handle this line specially. +All ebuilds committed to the tree should have a two line header immediately at +the start indicating copyright, followed by an empty line. This must be an +exact copy of the contents of +<c><uri link="https://gitweb.gentoo.org/repo/gentoo.git/tree/header.txt"> +header.txt</uri></c> in the top directory of the Gentoo repository. </p> <codesample lang="ebuild"> -# Copyright 1999-2006 Gentoo Foundation +# Copyright 1999-2024 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ </codesample> +<note> +The header previously included a third line with a CVS <c>$Id$</c> +or <c>$Header$</c> keyword. That line was abolished after conversion +to Git by <uri link="https://bugs.gentoo.org/611234">decision of the Gentoo +Council on 28 February 2017</uri> and <e>must not</e> be added any more. +</note> + </body> </section> @@ -149,9 +215,9 @@ indenting, never inside strings. </p> <p> -Avoid trailing whitespace: repoman will warn you about this if your -ebuild contains trailing or leading whitespace (whitespace instead of -tabs for indentation) when you commit. +Avoid trailing whitespace: <c>pkgcheck</c> will warn you about this if your +ebuild contains trailing or leading whitespace (whitespace instead of tabs for +indentation) when you commit. </p> <p> @@ -167,9 +233,9 @@ positions wide, and multibyte characters are just one position wide. <title>Character Set</title> <body> <p> -All ebuilds (and eclasses, metadata files and ChangeLogs) must use the -UTF-8 character set. See <uri -link="https://wiki.gentoo.org/wiki/GLEP:31">GLEP 31</uri> +All ebuilds (and eclasses, metadata files, etc.) must use the +UTF-8 character set. +See <uri link="https://www.gentoo.org/glep/glep-0031.html">GLEP 31</uri> for details. </p> </body> diff --git a/ebuild-writing/functions/diagram.svg b/ebuild-writing/functions/diagram.svg index 34ae53b..9547fc7 100644 --- a/ebuild-writing/functions/diagram.svg +++ b/ebuild-writing/functions/diagram.svg @@ -1,318 +1,387 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> <svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" version="1.0" width="1100" height="80" - viewBox="0 100 830 80" + viewBox="-130 100 1100 80" id="svg2503"> + <metadata + id="metadata55"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> <defs id="defs2577" /> <desc id="desc2505">Ebuild Function Order</desc> <rect - width="1100" - height="1000" - x="-135" - y="-10" + width="1101.323" + height="85.745827" + x="-129.33987" + y="96.698219" id="background" - style="fill:#eeeeee" /> - <line - style="stroke:#000000;stroke-width:2.19613099" - id="line2593" - y2="125" - x2="372.11496" - y1="125" - x1="323.88504" /> + style="fill:#eeeeee;stroke-width:0.293003" /> <rect width="80" height="30" - x="-115" - y="110" + x="-7.6246438" + y="115.12637" id="rect2508" - style="fill:#ccccff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="-75.000008" - y="130" + x="32.375347" + y="135.12637" id="text2510" - style="text-anchor:middle">pkg_setup</text> - <g - transform="translate(-125,0)" - id="g2599"> - <line - id="line2512" - y2="125" - x2="130" - y1="125" - x1="90" - style="stroke:#000000;stroke-width:2" /> - <line - id="line2514" - y2="120" - x2="122" - y1="125" - x1="130" - style="stroke:#000000;stroke-width:2" /> - <line - id="line2516" - y2="130" - x2="122" - y1="125" - x1="130" - style="stroke:#000000;stroke-width:2" /> - </g> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_setup</text> <rect width="80" height="30" - x="4.9999924" - y="110" + x="109.90766" + y="115.12637" id="rect2518" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="44.999992" - y="130" + x="149.90767" + y="135.12637" id="text2520" - style="text-anchor:middle">src_unpack</text> - <line - x1="373" - y1="125" - x2="365" - y2="120" - id="line2524" - style="stroke:#000000;stroke-width:2" /> - <line - x1="373" - y1="125" - x2="365" - y2="130" - id="line2526" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_unpack</text> <rect width="80" height="30" - x="373" - y="110" + x="428.4689" + y="115.12637" id="rect2528" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="413" - y="130" + x="468.4689" + y="135.12637" id="text2530" - style="text-anchor:middle">src_compile</text> - <line - x1="453" - y1="125" - x2="493" - y2="125" - id="line2532" - style="stroke:#000000;stroke-width:2" /> - <line - x1="493" - y1="125" - x2="485" - y2="120" - id="line2534" - style="stroke:#000000;stroke-width:2" /> - <line - x1="493" - y1="125" - x2="485" - y2="130" - id="line2536" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_compile</text> <path - d="M 453,125 C 466.33333,125 473,129 473,137 C 473,145.66667 479.66667,150 493,150 L 573,150 C 586.33333,150 593,145.66667 593,137 C 593,129 599.66667,125 613,125" + d="m 509.22566,130.12637 c 11.55683,0 17.33525,4 17.33525,12 0,8.66667 5.77842,13 17.33525,13 h 69.34101 c 11.55683,0 17.33525,-4.33333 17.33525,-13 0,-8 5.77842,-12 17.33525,-12" id="path2538" - style="fill:none;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> <rect width="80" height="30" - x="493" - y="110" + x="538.37067" + y="115.12637" id="rect2540" - style="fill:#ccffcc;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccffcc;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="532.99994" - y="130" + x="578.37061" + y="135.12637" id="text2542" - style="text-anchor:middle">src_test</text> - <line - x1="572.99994" - y1="125" - x2="612.99994" - y2="125" - id="line2544" - style="stroke:#000000;stroke-width:2" /> - <line - x1="612.99994" - y1="125" - x2="604.99994" - y2="120" - id="line2546" - style="stroke:#000000;stroke-width:2" /> - <line - x1="612.99994" - y1="125" - x2="604.99994" - y2="130" - id="line2548" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_test</text> + <g + id="g915"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line2544" + y2="130.12637" + x2="647.90759" + y1="130.12637" + x1="619.22565" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2546" + y2="125.12637" + x2="639.90759" + y1="130.12637" + x1="647.90759" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2548" + y2="135.12637" + x2="639.90759" + y1="130.12637" + x1="647.90759" /> + </g> <rect width="80" height="30" - x="612.99994" - y="110" + x="649.09814" + y="115.12637" id="rect2550" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="652.99994" - y="130" + x="687.09814" + y="135.12637" id="text2552" - style="text-anchor:middle">src_install</text> - <line - x1="692.99994" - y1="125" - x2="732.99994" - y2="125" - id="line2554" - style="stroke:#000000;stroke-width:2" /> - <line - x1="732.99994" - y1="125" - x2="724.99994" - y2="120" - id="line2556" - style="stroke:#000000;stroke-width:2" /> - <line - x1="732.99994" - y1="125" - x2="724.99994" - y2="130" - id="line2558" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_install</text> + <g + id="g920"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line2554" + y2="130.12637" + x2="767.09814" + y1="130.12637" + x1="729.9978" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2556" + y2="125.12637" + x2="759.09814" + y1="130.12637" + x1="767.09814" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2558" + y2="135.12637" + x2="759.09814" + y1="130.12637" + x1="767.09814" /> + </g> <rect width="80" height="30" - x="732.99994" - y="110" + x="767.90759" + y="115.12637" id="rect2560" - style="fill:#ccccff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="772.99994" - y="130" + x="807.90759" + y="135.12637" id="text2562" - style="text-anchor:middle">pkg_preinst</text> - <line - x1="812.99994" - y1="125" - x2="852.99994" - y2="125" - id="line2564" - style="stroke:#000000;stroke-width:2" /> - <line - x1="852.99994" - y1="125" - x2="844.99994" - y2="120" - id="line2566" - style="stroke:#000000;stroke-width:2" /> - <line - x1="852.99994" - y1="125" - x2="844.99994" - y2="130" - id="line2568" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_preinst</text> + <g + id="g925"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line2564" + y2="130.12637" + x2="873.90759" + y1="130.12637" + x1="848.47461" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2566" + y2="125.12637" + x2="865.90759" + y1="130.12637" + x1="873.90759" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2568" + y2="135.12637" + x2="865.90759" + y1="130.12637" + x1="873.90759" /> + </g> <rect width="80" height="30" - x="852.99994" - y="110" + x="873.90759" + y="115.12637" id="rect2570" - style="fill:#ccccff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="892.99994" - y="130" + x="913.90759" + y="135.12637" id="text2572" - style="text-anchor:middle">pkg_postinst</text> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_postinst</text> <path - d="M -34.79404,125.20597 C -15.171638,125.20597 -5.3604277,130.80594 -5.3604277,142.00588 C -5.3604277,153.86465 4.4507723,159.79403 24.073182,159.79403 L 671.61258,159.79403 C 691.23498,159.79403 701.04619,153.86465 701.04619,142.00588 C 701.04619,130.80594 710.85739,125.20597 730.4798,125.20597" + d="m 71.583477,130.33234 c 17.871085,0 26.806636,5.59997 26.806636,16.79991 0,11.85877 8.935547,17.78815 26.806617,17.78815 h 589.74589 c 17.87109,0 26.80666,-5.92938 26.80666,-17.78815 0,-11.19994 8.93553,-16.79991 26.80662,-16.79991" id="path2574" - style="fill:none;stroke:#000000;stroke-width:2.41193652" /> + style="opacity:1;fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> <rect width="80" height="30" - x="245" - y="110" + x="322.2374" + y="115.12637" id="rect2583" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="286.13922" - y="129.99992" + x="363.37662" + y="135.12637" id="text2585" - style="text-anchor:middle">src_configure</text> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_configure</text> <rect width="80" height="30" - x="125" - y="110" + x="215.93536" + y="115.12637" id="rect2587" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="167.51736" - y="129.99992" + x="258.45276" + y="135.12637" id="text2589" - style="text-anchor:middle">src_prepare</text> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_prepare</text> + <rect + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" + id="rect880" + y="115.0796" + x="-113.90761" + height="30" + width="80" /> + <text + x="-73.904678" + y="135.12637" + id="text890" + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_pretend</text> <g - transform="translate(-5.0000077,0)" - id="g2604"> + id="g910"> <line - x1="90" - y1="125" - x2="130" - y2="125" - id="line2606" - style="stroke:#000000;stroke-width:2" /> + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2534" + y2="125.12637" + x2="529.90765" + y1="130.12637" + x1="537.90765" /> <line - x1="130" - y1="125" - x2="122" - y2="120" - id="line2608" - style="stroke:#000000;stroke-width:2" /> + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2536" + y2="135.12637" + x2="529.90765" + y1="130.12637" + x1="537.90765" /> <line - x1="130" - y1="125" - x2="122" - y2="130" - id="line2610" - style="stroke:#000000;stroke-width:2" /> + x1="512.47461" + y1="130.12637" + x2="537.90759" + y2="130.12637" + id="line890" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> + <line + x1="509.22568" + y1="130.12637" + x2="537.90759" + y2="130.12637" + id="line894" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> </g> <g - transform="translate(115,0)" - id="g2612"> + id="g904"> <line - style="stroke:#000000;stroke-width:2" - id="line2614" - y2="125" - x2="130" - y1="125" - x1="90" /> + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2524" + y2="125.12637" + x2="420.4689" + y1="130.12637" + x1="428.4689" /> <line - style="stroke:#000000;stroke-width:2" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2526" + y2="135.12637" + x2="420.4689" + y1="130.12637" + x1="428.4689" /> + <line + x1="403.03592" + y1="130.12637" + x2="428.4689" + y2="130.12637" + id="line902" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> + </g> + <g + id="g899"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" id="line2616" - y2="120" - x2="122" - y1="125" - x1="130" /> + y2="125.12637" + x2="314.2374" + y1="130.12637" + x1="322.2374" /> <line - style="stroke:#000000;stroke-width:2" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" id="line2618" - y2="130" - x2="122" - y1="125" - x1="130" /> + y2="135.12637" + x2="314.2374" + y1="130.12637" + x1="322.2374" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line904" + y2="130.12637" + x2="322.2374" + y1="130.12637" + x1="296.80441" /> + </g> + <g + id="g894"> + <line + x1="215.93535" + y1="130.12637" + x2="207.93535" + y2="125.12637" + id="line2608" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + x1="215.93535" + y1="130.12637" + x2="207.93535" + y2="135.12637" + id="line2610" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + x1="190.50237" + y1="130.12637" + x2="215.93535" + y2="130.12637" + id="line906" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> + </g> + <g + id="g884"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line884" + y2="125.12637" + x2="-15.624653" + y1="130.12637" + x1="-7.6246533" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line886" + y2="135.12637" + x2="-15.624653" + y1="130.12637" + x1="-7.6246533" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line916" + y2="130.12637" + x2="-7.6246533" + y1="130.12637" + x1="-33.057636" /> + </g> + <g + id="g889"> + <line + id="line2514" + y2="125.12637" + x2="101.90767" + y1="130.12637" + x1="109.90767" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + id="line2516" + y2="135.12637" + x2="101.90767" + y1="130.12637" + x1="109.90767" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + x1="72.807327" + y1="130.12637" + x2="109.90767" + y2="130.12637" + id="line920" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> </g> </svg> diff --git a/ebuild-writing/functions/pkg_config/text.xml b/ebuild-writing/functions/pkg_config/text.xml index 422089f..6446777 100644 --- a/ebuild-writing/functions/pkg_config/text.xml +++ b/ebuild-writing/functions/pkg_config/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_config/"> <chapter> <title>pkg_config</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_config</c></title> <body> <codesample lang="ebuild"> -pkg_config() -{ - eerror "This ebuild does not have a config function." +pkg_config() { + eerror "This ebuild does not have a config function." } </codesample> </body> @@ -49,18 +48,18 @@ Taken from the <c>mysql</c> ebuilds. Note the use of <c>${ROOT}</c>. <codesample lang="ebuild"> pkg_config() { - if [ ! -d "${ROOT}"/var/lib/mysql/mysql ] ; then - einfo "Press ENTER to create the mysql database and set proper" - einfo "permissions on it, or Control-C to abort now..." - read - "${ROOT}"/usr/bin/mysql_install_db - else - einfo "Hmm, it appears as though you already have the mysql" - einfo "database in place. If you are having problems trying" - einfo "to start mysqld, perhaps you need to manually run" - einfo "/usr/bin/mysql_install_db and/or check your config" - einfo "file(s) and/or database(s) and/or logfile(s)." - fi + if [[ ! -d ${ROOT}/var/lib/mysql/mysql ]] ; then + einfo "Press ENTER to create the mysql database and set proper" + einfo "permissions on it, or Control-C to abort now..." + read + "${ROOT}"/usr/bin/mysql_install_db + else + einfo "Hmm, it appears as though you already have the mysql" + einfo "database in place. If you are having problems trying" + einfo "to start mysqld, perhaps you need to manually run" + einfo "/usr/bin/mysql_install_db and/or check your config" + einfo "file(s) and/or database(s) and/or logfile(s)." + fi } </codesample> </body> diff --git a/ebuild-writing/functions/pkg_info/text.xml b/ebuild-writing/functions/pkg_info/text.xml index 44f3c77..2e6607b 100644 --- a/ebuild-writing/functions/pkg_info/text.xml +++ b/ebuild-writing/functions/pkg_info/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_info/"> <chapter> <title>pkg_info</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_info</c></title> <body> <codesample lang="ebuild"> -pkg_info() -{ - return +pkg_info() { + return } </codesample> </body> @@ -54,15 +53,19 @@ pkg_info() { <section> <title>Notes on <c>pkg_info</c></title> <body> + +<p> +This phase will be called when a package manager displays information about +a package. +</p> + <p> -this phase will be called when a package manager displays -information about a package. -within EAPI=4, this phase can also be called for non-installed -packages. +The <c>pkg_info</c> function may also be called by the package manager for +non-installed packages. Ebuild writers should note that dependencies may not be +available. </p> + </body> </section> - </chapter> </guide> - diff --git a/ebuild-writing/functions/pkg_nofetch/text.xml b/ebuild-writing/functions/pkg_nofetch/text.xml index f360607..fdf4639 100644 --- a/ebuild-writing/functions/pkg_nofetch/text.xml +++ b/ebuild-writing/functions/pkg_nofetch/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_nofetch/"> <chapter> <title>pkg_nofetch</title> @@ -32,15 +32,14 @@ <title>Default <c>pkg_nofetch</c></title> <body> <codesample lang="ebuild"> -pkg_nofetch() -{ - [ -z "${SRC_URI}" ] && return +pkg_nofetch() { + [[ -z ${A} ]] && return - echo "!!! The following are listed in SRC_URI for ${PN}:" - for MYFILE in `echo ${SRC_URI}`; do - echo "!!! $MYFILE" - done - return + elog "The following files cannot be fetched for ${PN}:" + local x + for x in ${A}; do + elog " ${x}" + done } </codesample> </body> @@ -51,12 +50,16 @@ pkg_nofetch() <body> <codesample lang="ebuild"> pkg_nofetch() { - einfo "Please download" - einfo " - ${P}-main.tar.bz2" - einfo " - ${P}-extras.tar.bz2" - einfo "from ${HOMEPAGE} and place them in ${DISTDIR}" + einfo "Please download" + einfo " - ${P}-main.tar.bz2" + einfo " - ${P}-extras.tar.bz2" + einfo "from ${HOMEPAGE} and place them in your DISTDIR directory." } </codesample> +<note> +The <c>DISTDIR</c> variable is not valid in <c>pkg_*</c> phases, so it must not +be referenced. +</note> </body> </section> @@ -64,8 +67,8 @@ pkg_nofetch() { <title>Notes on <c>pkg_nofetch</c></title> <body> <p> -This function is only triggered for packages which -have <c>RESTRICT="fetch"</c> (see <uri link="::general-concepts/mirrors#Restricting Automatic Mirroring"/>) +This function is only triggered for packages which have <c>RESTRICT="fetch"</c> +(see <uri link="::general-concepts/mirrors/#Restricting Automatic Mirroring"/>) set, and only if one or more components listed in <c>SRC_URI</c> are not already available in the <c>distfiles</c> directory. </p> diff --git a/ebuild-writing/functions/pkg_postinst/text.xml b/ebuild-writing/functions/pkg_postinst/text.xml index 8b86c4c..06b3330 100644 --- a/ebuild-writing/functions/pkg_postinst/text.xml +++ b/ebuild-writing/functions/pkg_postinst/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_postinst/"> <chapter> <title>pkg_postinst</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_postinst</c></title> <body> <codesample lang="ebuild"> -pkg_postinst() -{ - return +pkg_postinst() { + return } </codesample> </body> @@ -45,14 +44,14 @@ pkg_postinst() <body> <codesample lang="ebuild"> pkg_postinst() { - if $OLD_FLUXBOX_VERSION ; then - ewarn "You must restart fluxbox before using the [include] /directory/" - ewarn "feature if you are upgrading from an older fluxbox!" - ewarn " " - fi - elog "If you experience font problems, or if fluxbox takes a very" - elog "long time to start up, please try the 'disablexmb' USE flag." - elog "If that fails, please report bugs upstream." + if ${OLD_FLUXBOX_VERSION} ; then + ewarn "You must restart fluxbox before using the [include] /directory/" + ewarn "feature if you are upgrading from an older fluxbox!" + ewarn " " + fi + elog "If you experience font problems, or if fluxbox takes a very" + elog "long time to start up, please try the 'disablexmb' USE flag." + elog "If that fails, please report bugs upstream." } </codesample> </body> diff --git a/ebuild-writing/functions/pkg_postrm/text.xml b/ebuild-writing/functions/pkg_postrm/text.xml index fa2a21d..7e9b475 100644 --- a/ebuild-writing/functions/pkg_postrm/text.xml +++ b/ebuild-writing/functions/pkg_postrm/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_postrm/"> <chapter> <title>pkg_postrm</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_postrm</c></title> <body> <codesample lang="ebuild"> -pkg_postrm() -{ - return +pkg_postrm() { + return } </codesample> </body> @@ -44,8 +43,11 @@ pkg_postrm() <title>Sample <c>pkg_postrm</c></title> <body> <codesample lang="ebuild"> +inherit xdg-utils + pkg_postrm() { - fdo-mime_mime_database_update + xdg_desktop_database_update + xdg_mimeinfo_database_update } </codesample> </body> diff --git a/ebuild-writing/functions/pkg_preinst/text.xml b/ebuild-writing/functions/pkg_preinst/text.xml index 9cdeb4a..ee78f6c 100644 --- a/ebuild-writing/functions/pkg_preinst/text.xml +++ b/ebuild-writing/functions/pkg_preinst/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_preinst/"> <chapter> <title>pkg_preinst</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_preinst</c></title> <body> <codesample lang="ebuild"> -pkg_preinst() -{ - return +pkg_preinst() { + return } </codesample> </body> @@ -45,8 +44,8 @@ pkg_preinst() <body> <codesample lang="ebuild"> pkg_preinst() { - enewgroup foo - enewuser foo -1 /bin/false /dev/null foo + enewgroup foo + enewuser foo -1 /bin/false /dev/null foo } </codesample> </body> @@ -63,7 +62,7 @@ There are a few things that are often done in <c>pkg_preinst</c>: <li> Adding users and groups. However, since <c>pkg_preinst</c> may be called after <c>src_compile</c>, <c>pkg_setup</c> is the more suitable location for - user creation <d/> see <uri link="::ebuild-writing/users-and-groups"/>. + user creation <d/> see <uri link="::ebuild-writing/users-and-groups/"/>. </li> <li> Modifying the install image for a particular system. This function @@ -72,9 +71,9 @@ There are a few things that are often done in <c>pkg_preinst</c>: configuration file updating <d/> a <c>pkg_preinst</c> could check a configuration file in <c>${ROOT}/etc/</c> and create a smart updated version in <c>${D}/etc/</c> (see - <uri link="::general-concepts/install-destinations"/>) rather than + <uri link="::general-concepts/install-destinations/"/>) rather than always trying to install the default configuration file (remember - <uri link="::general-concepts/config-protect"/>). + <uri link="::general-concepts/config-protect/"/>). </li> </ul> </body> diff --git a/ebuild-writing/functions/pkg_prerm/text.xml b/ebuild-writing/functions/pkg_prerm/text.xml index d9f8a6f..7522624 100644 --- a/ebuild-writing/functions/pkg_prerm/text.xml +++ b/ebuild-writing/functions/pkg_prerm/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_prerm/"> <chapter> <title>pkg_prerm</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_prerm</c></title> <body> <codesample lang="ebuild"> -pkg_prerm() -{ - return +pkg_prerm() { + return } </codesample> </body> @@ -45,8 +44,8 @@ pkg_prerm() <body> <codesample lang="ebuild"> pkg_prerm() { - # clean up temp files - [[ -d "${ROOT}/var/tmp/foo" ]] && rm -rf "${ROOT}/var/tmp/foo" + # clean up temp files + [[ -d "${ROOT}/var/tmp/foo" ]] && rm -rf "${ROOT}/var/tmp/foo" } </codesample> </body> diff --git a/ebuild-writing/functions/pkg_pretend/text.xml b/ebuild-writing/functions/pkg_pretend/text.xml index 0279145..a838757 100644 --- a/ebuild-writing/functions/pkg_pretend/text.xml +++ b/ebuild-writing/functions/pkg_pretend/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_pretend/"> <chapter> <title>pkg_pretend</title> @@ -23,11 +23,11 @@ </tr> <tr> <th>Called for</th> - <ti>ebuild</ti> + <ti>ebuild, binary</ti> </tr> <tr> <th>EAPI</th> - <ti>3</ti> + <ti>4</ti> </tr> </table> </body> @@ -36,9 +36,8 @@ <title>Default <c>pkg_pretend</c></title> <body> <codesample lang="ebuild"> -pkg_pretend() -{ - return +pkg_pretend() { + return } </codesample> </body> @@ -67,12 +66,13 @@ pkg_pretend() { <title>Notes on <c>pkg_pretend</c></title> <body> <p> -the <c>pkg_pretend</c> phase can be used to do sanity checks +The <c>pkg_pretend</c> phase can be used to do sanity checks before the main phase function sequence is run (meaning this phase is executed after the package manager has calculated the dependencies and before installing them). This phase typically checks for a kernel configuration and may <c>eerror</c> and <c>die</c> when needed. +</p> <important> There is no guarantee that the ebuild's dependencies are installed when this phase is called. @@ -81,7 +81,6 @@ This phase typically checks for a kernel configuration and may As <c>pkg_pretend</c> is not called in the main phase function sequence, environment saving is not guaranteed. </important> -</p> </body> </section> diff --git a/ebuild-writing/functions/pkg_setup/text.xml b/ebuild-writing/functions/pkg_setup/text.xml index a7fe9d2..90f89cf 100644 --- a/ebuild-writing/functions/pkg_setup/text.xml +++ b/ebuild-writing/functions/pkg_setup/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_setup/"> <chapter> <title>pkg_setup</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_setup</c></title> <body> <codesample lang="ebuild"> -pkg_setup() -{ - return +pkg_setup() { + return } </codesample> </body> @@ -45,19 +44,19 @@ pkg_setup() <body> <codesample lang="ebuild"> pkg_setup() { - # We need to know which GUI we're building in several - # different places, so work it out here. - if use gtk ; then - if use gtk2 ; then - export mypkg_gui="gtk2" - else - export mypkg_gui="gtk1" - fi - elif use motif then - export mypkg_gui="motif" - else - export mypkg_gui="athena" - fi + # We need to know which GUI we're building in several + # different places, so work it out here. + if use gtk ; then + if use gtk2 ; then + export mypkg_gui="gtk2" + else + export mypkg_gui="gtk1" + fi + elif use motif then + export mypkg_gui="motif" + else + export mypkg_gui="athena" + fi } </codesample> </body> diff --git a/ebuild-writing/functions/src_compile/build-environment/text.xml b/ebuild-writing/functions/src_compile/build-environment/text.xml index 8c16587..1aa826e 100644 --- a/ebuild-writing/functions/src_compile/build-environment/text.xml +++ b/ebuild-writing/functions/src_compile/build-environment/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_compile/build-environment/"> <chapter> <title>Configuring Build Environment</title> @@ -17,8 +17,8 @@ Except where otherwise specified, any function which operates on </note> <p> -Ebuilds must not simply ignore user CFLAGS, CXXFLAGS or LDFLAGS<d/> see -<uri link="::general-concepts/user-environment#Not Filtering Variables"/>. +Ebuilds must not simply ignore user CFLAGS, CXXFLAGS or LDFLAGS <d/> see +<uri link="::general-concepts/user-environment/#Not Filtering Variables"/>. </p> </body> @@ -69,9 +69,9 @@ remove. </p> <codesample lang="ebuild"> - # -fomit-frame-pointer leads to nasty broken code on sparc thanks to a - # rather icky asm function - use sparc && filter-flags -fomit-frame-pointer + # -fomit-frame-pointer leads to nasty broken code on sparc thanks to a + # rather icky asm function + use sparc && filter-flags -fomit-frame-pointer </codesample> <p> @@ -86,8 +86,8 @@ conservative set of flags. </p> <codesample lang="ebuild"> - # Our app hates screwy flags - strip-flags + # Our app hates screwy flags + strip-flags </codesample> </body> @@ -104,8 +104,8 @@ is most commonly used to replace <c>-Os</c> with <c>-O2</c> </p> <codesample lang="ebuild"> - # Seems to have issues with -Os, switch to -O2 - replace-flags -Os -O2 + # Seems to have issues with -Os, switch to -O2 + replace-flags -Os -O2 </codesample> <p> @@ -116,8 +116,8 @@ the flags to be replaced. </p> <codesample lang="ebuild"> - # Can't use ultrasparc or ultrasparc3 code, drop to v9 - replace-cpu-flags ultrasparc ultrasparc3 v9 + # Can't use ultrasparc or ultrasparc3 code, drop to v9 + replace-cpu-flags ultrasparc ultrasparc3 v9 </codesample> </body> @@ -133,15 +133,15 @@ functions can be used here. </p> <codesample lang="ebuild"> - # If we're using selinux, we need to add a -D - use selinux && append-flags "-DWITH_SELINUX" + # If we're using selinux, we need to add a -D + use selinux && append-flags "-DWITH_SELINUX" - # Secure linking needed, since we're setuid root - append-ldflags -Wl,-z,now + # Secure linking needed, since we're setuid root + append-ldflags -Wl,-z,now </codesample> <p> -See <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic.eclass</uri> for a full reference. +See <uri link="::eclass-reference/flag-o-matic.eclass/"/> for a full reference. </p> </body> </section> diff --git a/ebuild-writing/functions/src_compile/building/text.xml b/ebuild-writing/functions/src_compile/building/text.xml index bed3dd7..9ac9c13 100644 --- a/ebuild-writing/functions/src_compile/building/text.xml +++ b/ebuild-writing/functions/src_compile/building/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_compile/building/"> <chapter> <title>Building a Package</title> @@ -20,9 +20,9 @@ cleanly, it should be patched. <p> If patching <e>really</e> isn't an option, <c>emake -j1</c> should be -used. However, when doing this please remember that you are seriously +used. However, when doing this, please remember that you are seriously hurting build times for many non-x86 users in particular. Forcing -a <c>-j1</c> can increase build times from a few minutes to an hour on +<c>-j1</c> can increase build times from a few minutes to an hour on some MIPS and SPARC systems. </p> </body> @@ -34,8 +34,18 @@ some MIPS and SPARC systems. <p> Sometimes a package will try to use a bizarre compiler, or will need to be told which compiler to use. In these situations, the <c>tc-getCC()</c> function from -<uri link="::eclass-reference/toolchain-funcs.eclass/">toolchain-funcs.eclass</uri> should be used. Other similar functions are available -<d/> these are documented in <c>man toolchain-funcs.eclass</c>. +<uri link="::eclass-reference/toolchain-funcs.eclass/"/> should be used. +Other similar functions are available <d/> these are documented in +<c>man toolchain-funcs.eclass</c>. +</p> + +<p> +Note that packages should always respect the user's <c>CC</c> preference +and must not rely on convenience symlinks such as <c>/usr/bin/cc</c> +or <c>/usr/bin/gcc</c>. A tracker <uri link="https://bugs.gentoo.org/243502"> +bug</uri> exists to document such issues. Additional documentation exists on the +<uri link="https://wiki.gentoo.org/wiki/Project:Toolchain/use_native_symlinks"> +wiki</uri>. </p> <note> @@ -46,27 +56,39 @@ It is <e>not</e> correct to use the <c>${CC}</c> variable for this purpose. Sometimes a package will not use the user's <c>${CFLAGS}</c> or <c>${LDFLAGS}</c>. This must be worked around, as sometimes these variables are used for specifying critical ABI options. In these cases, the build scripts should be modified (for -example, with <c>sed</c>) to use <c>${CFLAGS}</c> or <c>${LDFLAGS}</c> correctly. +example, with <c>sed</c> or via a patch) to use <c>${CFLAGS}</c> or +<c>${LDFLAGS}</c> correctly. </p> <codesample lang="ebuild"> inherit flag-o-matic toolchain-funcs +src_prepare() { + default + + # We have a weird Makefile to work with which ignores our + # compiler preferences. yay! + # Note the single quotes (hence the delimiter is not an issue) + sed -i -e 's:cc -O2:$(CC) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS):' Makefile \ + || die "sed fix failed. Uh-oh..." +} + src_compile() { - # -Os not happy - replace-flags -Os -O2 - - # We have a weird build.sh to work with which ignores our - # compiler preferences. yay! - sed -i -e "s:cc -O2:$(tc-getCC) ${CFLAGS} ${LDFLAGS}:" build.sh \ - || die "sed fix failed. Uh-oh..." - ./build.sh || die "Build failed!" + # -Os not happy + replace-flags -Os -O2 + + emake CC="$(tc-getCC)" \ + CPPFLAGS="${CPPFLAGS}" \ + CFLAGS="${CFLAGS}" \ + LDFLAGS="${LDFLAGS}" } </codesample> <note> -When using <c>sed</c> with <c>CFLAGS</c> or <c>LDFLAGS</c>, it is not safe to use -a comma or a slash as a delimiter. The recommended character is a colon. +Try to not substitute the value with <c>sed</c> directly, but instead make the +build script use the variables. The variables may contain characters such as a +slash, a comma, or a colon, which are often used with <c>sed</c>, and this +would break its syntax. </note> <p> diff --git a/ebuild-writing/functions/src_compile/no-build-system/text.xml b/ebuild-writing/functions/src_compile/no-build-system/text.xml index 99b873a..e4e878a 100644 --- a/ebuild-writing/functions/src_compile/no-build-system/text.xml +++ b/ebuild-writing/functions/src_compile/no-build-system/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_compile/no-build-system/"> <chapter> <title>No Build System</title> @@ -14,7 +14,7 @@ Here's an example, from <c>app-misc/hilite</c>: <codesample lang="ebuild"> src_compile() { - $(tc-getCC) ${LDFLAGS} ${CFLAGS} -o ${PN} ${P}.c || die + $(tc-getCC) ${CFLAGS} ${CPPFLAGS} ${LDFLAGS} -o ${PN} ${P}.c || die } </codesample> @@ -25,29 +25,29 @@ broken build system that doesn't actually work: <codesample lang="ebuild"> src_compile() { - local x - for x in asclock parser symbols config - do - $(tc-getCC) \ - ${CPPFLAGS} ${CFLAGS} ${ASFLAGS} \ - -I/usr/include \ - -Dlinux \ - -D_POSIX_C_SOURCE=199309L \ - -D_POSIX_SOURCE \ - -D_XOPEN_SOURCE \ - -D_BSD_SOURCE \ - -D_SVID_SOURCE \ - -DFUNCPROTO=15 \ - -DNARROWPROTO \ - -c -o ${x}.o ${x}.c || die "compile asclock failed" - done - $(tc-getCC) \ - ${LDFLAGS} \ - -o asclock \ - asclock.o parser.o symbols.o config.o \ - -L/usr/lib \ - -L/usr/lib/X11 \ - -lXpm -lXext -lX11 || die "link asclock failed" + local x + for x in asclock parser symbols config + do + $(tc-getCC) \ + ${CPPFLAGS} ${CFLAGS} ${ASFLAGS} \ + -I"${EPREFIX}"/usr/include \ + -Dlinux \ + -D_POSIX_C_SOURCE=199309L \ + -D_POSIX_SOURCE \ + -D_XOPEN_SOURCE \ + -D_BSD_SOURCE \ + -D_SVID_SOURCE \ + -DFUNCPROTO=15 \ + -DNARROWPROTO \ + -c -o ${x}.o ${x}.c || die "compile asclock failed" + done + $(tc-getCC) \ + ${LDFLAGS} \ + -o asclock \ + asclock.o parser.o symbols.o config.o \ + -L"${EPREFIX}"/usr/lib \ + -L"${EPREFIX}"/usr/lib/X11 \ + -lXpm -lXext -lX11 || die "link asclock failed" } </codesample> diff --git a/ebuild-writing/functions/src_compile/text.xml b/ebuild-writing/functions/src_compile/text.xml index 89350cb..abe67d9 100644 --- a/ebuild-writing/functions/src_compile/text.xml +++ b/ebuild-writing/functions/src_compile/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_compile/"> <chapter> <title>src_compile</title> @@ -11,7 +11,7 @@ </tr> <tr> <th>Purpose</th> - <ti>Configure and build the package.<important>the configure parts of <c>src_compile</c> have been splitted out in EAPI=2 to <c>src_configure</c>. see <uri link="::ebuild-writing/functions/src_configure"/></important></ti> + <ti>Build the package.</ti> </tr> <tr> <th>Sandbox</th> @@ -30,70 +30,44 @@ <section> <title>Default <c>src_compile</c></title> + <body> -<subsection> -<title>with EAPI=0,1</title> -<body> -<codesample lang="ebuild"> -src_compile() { - if [ -x ./configure ]; then - econf - fi - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then - emake || die "emake failed" - fi -} -</codesample> -</body> -</subsection> -<subsection> -<title>with EAPI=2</title> -<body> +<ul> + <li> <codesample lang="ebuild"> src_compile() { - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then - emake || die "emake failed" - fi + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then + emake || die "emake failed" + fi } </codesample> -</body> -</subsection> + </li> +</ul> </body> </section> <section> <title>Sample <c>src_compile</c></title> <body> -<subsection> -<title>with EAPI=0</title> -<body> + +<ul> + <li> <codesample lang="ebuild"> src_compile() { - use sparc && filter-flags -fomit-frame-pointer - append-ldflags -Wl,-z,now - - econf \ - $(use_enable ssl ) \ - $(use_enable perl perlinterp ) + use sparc && filter-flags -fomit-frame-pointer + append-ldflags -Wl,-z,now - emake || die "Make failed!" + emake } </codesample> -<note> -You also need to inherit the <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> eclass in order to use the <c>append-ldflags</c> function. -</note> -</body> -</subsection> -<subsection> -<title>with EAPI=2</title> -<body> -<p> -porting the above example to EAPI=2, you won't need to define an extra -<c>src_compile</c>, as it only calls <c>emake</c> (which is the default -<c>src_compile</c> function). -</p> -</body> -</subsection> + <note> + You also need to inherit the + <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> + eclass in order to use the <c>append-ldflags</c> function. + </note> + </li> +</ul> + </body> </section> @@ -112,7 +86,6 @@ The following subsections cover different topics which often occur when writing </chapter> <include href="build-environment/"/> -<!--<include href="configuring/"/>--> <include href="building/"/> <include href="no-build-system/"/> </guide> diff --git a/ebuild-writing/functions/src_configure/configuring/text.xml b/ebuild-writing/functions/src_configure/configuring/text.xml index 677334e..14672c4 100644 --- a/ebuild-writing/functions/src_configure/configuring/text.xml +++ b/ebuild-writing/functions/src_configure/configuring/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_configure/configuring/"> <chapter> <title>Configuring a Package</title> @@ -30,18 +30,18 @@ where appropriate, be used to generate these switches. <codesample lang="ebuild"> src_configure() { - # We have optional perl, python and ruby support - econf \ - $(use_enable perl ) \ - $(use_enable python ) \ - $(use_enable ruby ) + # We have optional perl, python and ruby support + econf \ + $(use_enable perl) \ + $(use_enable python) \ + $(use_enable ruby) } src_configure() { - # Our package optional IPv6 support which uses --with rather than - # --enable / --disable + # Our package optional IPv6 support which uses --with rather than + # --enable / --disable - econf $(use_with ipv6 ) + econf $(use_with ipv6) } </codesample> @@ -54,17 +54,17 @@ argument forms: <codesample lang="ebuild"> src_configure() { - # Our package has optional perl, python and ruby support - econf \ - $(use_enable perl perlinterp ) \ - $(use_enable python pythoninterp ) \ - $(use_enable ruby rubyinterp ) + # Our package has optional perl, python and ruby support + econf \ + $(use_enable perl perlinterp) \ + $(use_enable python pythoninterp) \ + $(use_enable ruby rubyinterp) - # ... + # ... } -src_compile() { - econf $(use_with X x11 ) +src_configure() { + econf $(use_with X x11) } </codesample> @@ -74,5 +74,56 @@ form can be used. </p> </body> +<section> +<title><c>econf</c> Options</title> +<body> + +<p> +<c>econf</c> is designed to work with configure scripts generated by +GNU Autoconf. It first passes the default options listed below to the configure +script, followed by any additional parameters passed to <c>econf</c>. +</p> + +<ul> + <li><c>--prefix="${EPREFIX}"/usr</c></li> + <li><c>--mandir="${EPREFIX}"/usr/share/man</c></li> + <li><c>--infodir="${EPREFIX}"/usr/share/info</c></li> + <li><c>--datadir="${EPREFIX}"/usr/share</c></li> + <li><c>--sysconfdir="${EPREFIX}"/etc</c></li> + <li><c>--localstatedir="${EPREFIX}"/var/lib</c></li> + <li> + <c>--build="${CBUILD}"</c> (only passed if <c>CBUILD</c> is non-empty) + </li> + <li><c>--host="${CHOST}"</c></li> + <li> + <c>--target="${CTARGET}"</c> (only passed if <c>CTARGET</c> is non-empty) + </li> + <li> + <c>--libdir</c> is set from the value of the <c>LIBDIR_${ABI}</c> variable + in profiles. + </li> + <li><c>--disable-dependency-tracking</c></li> + <li><c>--disable-silent-rules</c></li> +</ul> + +<p> +In EAPI 6 and later, the following options are passed in addition: +</p> + +<ul> + <li><c>--docdir="${EPREFIX}"/usr/share/doc/${PF}</c></li> + <li><c>--htmldir="${EPREFIX}"/usr/share/doc/${PF}/html</c></li> +</ul> + +<p> +In EAPI 7 and later, the following option is passed in addition: +</p> + +<ul> + <li><c>--with-sysroot="${ESYSROOT:-/}"</c></li> +</ul> + +</body> +</section> </chapter> </guide> diff --git a/ebuild-writing/functions/src_configure/text.xml b/ebuild-writing/functions/src_configure/text.xml index 0740309..03f9583 100644 --- a/ebuild-writing/functions/src_configure/text.xml +++ b/ebuild-writing/functions/src_configure/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_configure/"> <chapter> <title>src_configure</title> @@ -38,8 +38,8 @@ <codesample lang="ebuild"> src_configure() { if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then - econf - fi + econf + fi } </codesample> </body> @@ -49,15 +49,24 @@ src_configure() { <title>Sample <c>src_configure</c></title> <body> <codesample lang="ebuild"> +inherit flag-o-matic + src_configure() { - use sparc && filter-flags -fomit-frame-pointer - append-ldflags -Wl,-z,now + use sparc && filter-flags -fomit-frame-pointer + append-ldflags -Wl,-z,now - econf \ - $(use_enable ssl ) \ - $(use_enable perl perlinterp ) + econf \ + $(use_enable ssl) \ + $(use_enable perl perlinterp) } </codesample> + +<note> +You also need to inherit the +<uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> +eclass in order to use the <c>append-ldflags</c> function. +</note> + </body> </section> @@ -76,8 +85,5 @@ The following subsections cover different topics which often occur when writing </chapter> <include href="configuring/"/> -<!--<include href="build-environment/"/> -<include href="building/"/> -<include href="no-build-system/"/>--> </guide> diff --git a/ebuild-writing/functions/src_install/docompress/text.xml b/ebuild-writing/functions/src_install/docompress/text.xml new file mode 100644 index 0000000..ed1634b --- /dev/null +++ b/ebuild-writing/functions/src_install/docompress/text.xml @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-writing/functions/src_install/docompress/"> +<chapter> +<title>Controllable Compression</title> +<body> + +<p> +You can call the <c>docompress</c> function in <c>src_install</c> to control +which items in the destination folder <c>${D}</c> should be compressed and +which shouldn't be compressed. You can include or exclude directories or plain +files. The default inclusion list contains: +</p> + +<ul> + <li><c>/usr/share/doc</c></li> + <li><c>/usr/share/info</c></li> + <li><c>/usr/share/man</c></li> +</ul> + +<p> +The default exclusion list contains: +</p> + +<ul> + <li><c>/usr/share/doc/${PF}/html</c></li> +</ul> + +<p> +When a directory is in- or excluded, all files and directories in the given +directories shall be added to the corresponding list. If a file is in- or +excluded, the file shall be added to the corresponding list (exclusion is +stronger than inclusion <d/> if a file is in both lists, the inclusion will +be ignored). +</p> + +<p> +If the first argument of <c>docompress</c> is <c>-x</c>, the items specified +will be added to the exclusion list, otherwise they will be added to the +inclusion list. +</p> + +<note> +When <c>docompress</c> is called, it is <e>not</e> required that the paths +specified as its arguments are pointing to existing files or directories. +However, if a file still doesn't exist when <c>src_install</c> has completed, +it will be ignored with a warning. +</note> + +</body> +</chapter> +</guide> diff --git a/ebuild-writing/functions/src_install/text.xml b/ebuild-writing/functions/src_install/text.xml index 530baf1..66a8e3d 100644 --- a/ebuild-writing/functions/src_install/text.xml +++ b/ebuild-writing/functions/src_install/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_install/"> <chapter> <title>src_install</title> @@ -31,39 +31,41 @@ <section> <title>Default <c>src_install</c></title> <body> -<p> -For EAPIs 0,1,2, and 3, the default <c>src_install</c> function is the -following: -</p> -<codesample lang="ebuild"> -src_install() -{ - return -} -</codesample> + <p> For EAPIs 4 and later, the default <c>src_install</c> function is the following: </p> <codesample lang="ebuild"> src_install() { - if [[ -f Makefile ]] || [[ -f GNUmakefile]] || [[ -f makefile ]] ; then + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]] ; then emake DESTDIR="${D}" install fi - if ! declare -p DOCS >/dev/null 2>&1 ; then + if ! declare -p DOCS >/dev/null 2>&1 ; then local d for d in README* ChangeLog AUTHORS NEWS TODO CHANGES THANKS BUGS \ FAQ CREDITS CHANGELOG ; do [[ -s "${d}" ]] && dodoc "${d}" done - elif declare -p DOCS | grep -q "^declare -a " ; then + elif [[ $(declare -p DOCS) == "declare -a"* ]] ; then dodoc "${DOCS[@]}" else dodoc ${DOCS} fi } </codesample> -<important>The following examples assume EAPI 4 or later</important> +<p> +For EAPIs 6 and later, the default <c>src_install</c> function is the following: +</p> +<codesample lang="ebuild"> +src_install() { + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]] ; then + emake DESTDIR="${D}" install + fi + einstalldocs +} +</codesample> + </body> </section> @@ -73,8 +75,8 @@ src_install() { <codesample lang="ebuild"> src_install() { - emake DESTDIR="${D}" install - dodoc README CHANGES + emake DESTDIR="${D}" install + dodoc README CHANGES } </codesample> @@ -91,7 +93,7 @@ install to a non-root location. If possible, this should be used: </p> <codesample lang="ebuild"> - emake DESTDIR="${D}" install + emake DESTDIR="${D}" install </codesample> <note> @@ -101,18 +103,22 @@ if you hit an error. </note> <p> - Sometimes this will end up installing a few things into strange - places. If and only if this is the case, the <c>einstall</c> - function can be used. It is usually necessary to include additional - <c>dodoc</c> statements for the <c>README</c>, <c>ChangeLog</c>, etc - in these cases: +Usually the package's build system will not install the <c>README</c>, +<c>ChangeLog</c>, etc. files, so it is necessary to include additional +<c>dodoc</c> statements for them: </p> <codesample lang="ebuild"> - einstall - dodoc README CHANGES + emake DESTDIR="${D}" install + dodoc README CHANGES + dodoc -r doc </codesample> +<p> +<c>dodoc</c> supports <c>-r</c> as the first argument, which allows directories +to be installed recursively. +</p> + <note> There is no need to <c>dodoc</c> <c>COPYING</c>! The license belongs to <c>${PORTDIR}/licenses</c>. Sometimes though, you might want to @@ -135,64 +141,64 @@ compilation required) themes: </p> <codesample lang="ebuild"> - dodir /usr/share/foo-styles/ - cp -R "${S}/" "${D}/" || die "Install failed!" + dodir /usr/share/foo-styles/ + cp -R "${S}/" "${D}/" || die "Install failed!" </codesample> <p> Or sometimes a combination of <c>insinto</c> and <c>doins</c> (plus related -functions -- see <uri link="::function-reference/install-functions"/>) <d/> the following is based -upon the <c>sys-fs/udev</c> install: +functions <d/> see <uri link="::function-reference/install-functions/"/>) <d/> +the following is based upon the <c>sys-fs/udev</c> install: </p> <codesample lang="ebuild"> src_install() { - dobin udevinfo - dobin udevtest - into / - dosbin udev - dosbin udevd - dosbin udevsend - dosbin udevstart - dosbin extras/scsi_id/scsi_id - dosbin extras/volume_id/udev_volume_id - - exeinto /etc/udev/scripts - doexe extras/ide-devfs.sh - doexe extras/scsi-devfs.sh - doexe extras/cdsymlinks.sh - doexe extras/dvb.sh - - insinto /etc/udev - newins "${FILESDIR}/udev.conf.post_050" udev.conf - doins extras/cdsymlinks.conf - - # For devfs style layout - insinto /etc/udev/rules.d/ - newins etc/udev/gentoo/udev.rules 50-udev.rules - - # scsi_id configuration - insinto /etc - doins extras/scsi_id/scsi_id.config - - # set up symlinks in /etc/hotplug.d/default - dodir /etc/hotplug.d/default - dosym ../../../sbin/udevsend /etc/hotplug.d/default/10-udev.hotplug - - # set up the /etc/dev.d directory tree - dodir /etc/dev.d/default - dodir /etc/dev.d/net - exeinto /etc/dev.d/net - doexe etc/dev.d/net/hotplug.dev - - doman *.8 - doman extras/scsi_id/scsi_id.8 - - dodoc ChangeLog FAQ HOWTO-udev_for_dev README TODO - dodoc docs/{overview,udev-OLS2003.pdf,udev_vs_devfs,RFC-dev.d,libsysfs.txt} - dodoc docs/persistent_naming/* docs/writing_udev_rules/* - - newdoc extras/volume_id/README README_volume_id + dobin udevinfo + dobin udevtest + into / + dosbin udev + dosbin udevd + dosbin udevsend + dosbin udevstart + dosbin extras/scsi_id/scsi_id + dosbin extras/volume_id/udev_volume_id + + exeinto /etc/udev/scripts + doexe extras/ide-devfs.sh + doexe extras/scsi-devfs.sh + doexe extras/cdsymlinks.sh + doexe extras/dvb.sh + + insinto /etc/udev + newins "${FILESDIR}/udev.conf.post_050" udev.conf + doins extras/cdsymlinks.conf + + # For devfs style layout + insinto /etc/udev/rules.d/ + newins etc/udev/gentoo/udev.rules 50-udev.rules + + # scsi_id configuration + insinto /etc + doins extras/scsi_id/scsi_id.config + + # set up symlinks in /etc/hotplug.d/default + dodir /etc/hotplug.d/default + dosym ../../../sbin/udevsend /etc/hotplug.d/default/10-udev.hotplug + + # set up the /etc/dev.d directory tree + dodir /etc/dev.d/default + dodir /etc/dev.d/net + exeinto /etc/dev.d/net + doexe etc/dev.d/net/hotplug.dev + + doman *.8 + doman extras/scsi_id/scsi_id.8 + + dodoc ChangeLog FAQ HOWTO-udev_for_dev README TODO + dodoc docs/{overview,udev-OLS2003.pdf,udev_vs_devfs,RFC-dev.d,libsysfs.txt} + dodoc docs/persistent_naming/* docs/writing_udev_rules/* + + newdoc extras/volume_id/README README_volume_id } </codesample> @@ -215,5 +221,20 @@ upstream explaining the situation to them. </body> </section> +<section> +<title><c>src_install</c> Processes</title> +<body> + +<p> +The following subsections cover different topics which often occur when writing +<c>src_install</c> functions. +</p> + +<contentsTree/> + +</body> +</section> </chapter> + +<include href="docompress/"/> </guide> diff --git a/ebuild-writing/functions/src_prepare/autopackage/text.xml b/ebuild-writing/functions/src_prepare/autopackage/text.xml index 56c6b47..42fb255 100644 --- a/ebuild-writing/functions/src_prepare/autopackage/text.xml +++ b/ebuild-writing/functions/src_prepare/autopackage/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_prepare/autopackage/"> <chapter> <title>Autopackage</title> diff --git a/ebuild-writing/functions/src_prepare/epatch/text.xml b/ebuild-writing/functions/src_prepare/epatch/text.xml index 1322a5e..ba77549 100644 --- a/ebuild-writing/functions/src_prepare/epatch/text.xml +++ b/ebuild-writing/functions/src_prepare/epatch/text.xml @@ -1,23 +1,79 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_prepare/epatch/"> <chapter> -<title>Patching with epatch</title> +<title>Patching with epatch and eapply</title> <body> <p> The canonical way of applying patches in ebuilds is to -use <c>epatch</c> (from <c>eutils.eclass</c>, which you must make sure -to import!) inside <c>src_prepare</c>. This function automatically -handles <c>-p</c> levels, <c>gunzip</c> and so on as necessary. Also note that olds ebuild may still use src_unpack to apply patches. This is because those ebuilds are based in EAPI="1". You are advised to use EAPI="2" and apply your patches in src_prepare function instead. +use <c>epatch</c> (from <c>epatch.eclass</c>, which you must make sure +to inherit!) inside <c>src_prepare</c>. This function automatically +handles <c>-p</c> levels, <c>gunzip</c> and so on as necessary. </p> <p> +Starting with EAPI=7, this function is banned and <c>eapply</c> must be used. +</p> + +<p> +Beginning with EAPI=6, a new function <c>eapply</c> was added to apply patches +without the need for an eclass. +This function differs from epatch in several ways: +</p> + +<ul> +<li><c>eapply</c> will not unpack patches for you.</li> +<li> +The default patch level is -p1. +Other patch levels must be specified manually or the command will fail. +</li> +<li> +When specifying a directory, at least one file with a name ending in .patch or .diff +must exist or the command fails. Other files are ignored. +</li> +</ul> + +<p> Note that distributing modified tarballs rather than a vanilla tarball and patches is <e>highly</e> discouraged. </p> </body> <section> +<title>Basic <c>eapply</c></title> +<body> +<p> +The default src_prepare function will look for a global PATCHES array to apply +a list of patches for you. +</p> +<codesample lang="ebuild"> +PATCHES=( + "${FILESDIR}/${P}-destdir.patch" + "${FILESDIR}/${P}-parallel_build.patch" +) +</codesample> +</body> +</section> + +<section> +<title>Advanced <c>eapply</c></title> +<body> +<p> +This example shows how different patch levels can be applied: +</p> + +<codesample lang="ebuild"> +src_prepare() { + eapply -p2 "${WORKDIR}/${P}-suse-update.patch" + eapply -p0 "${FILESDIR}/${PV}-no-TIOCGDEV.patch" + eapply "${FILESDIR}/${PV}-gcc-6.patch" + eapply_user +} +</codesample> +</body> +</section> + +<section> <title>Basic <c>epatch</c></title> <body> @@ -28,32 +84,24 @@ fails. The following is taken from <c>app-misc/detox</c>: </p> <codesample lang="ebuild"> -src_unpack() { - unpack ${A} - cd "${S}" - epatch "${FILESDIR}/${P}-destdir.patch" - epatch "${FILESDIR}/${P}-parallel_build.patch" +src_prepare() { + epatch "${FILESDIR}/${P}-destdir.patch" + epatch "${FILESDIR}/${P}-parallel_build.patch" } </codesample> <p> -For larger patches, using <uri link="::general-concepts/mirrors/#suitable-download-hosts">your devspace</uri> rather -than <c>files/</c> is more appropriate. In these situations, it is -usually best to <c>bzip2</c> the patch in question (as opposed to -<c>files/</c> patches, which must not be compressed). For example, -from <c>app-admin/showconsole</c>: +For larger patches, using +<uri link="::general-concepts/mirrors/#Suitable Download Hosts"> +your devspace</uri> rather than +<uri link="::ebuild-writing/variables/#Predefined Read-Only Variables"> +${FILESDIR}</uri> is more appropriate. In these situations, it is +usually best to compress the patch in question with <c>xz</c> or +<c>bzip2</c> (as opposed to <c>${FILESDIR}</c> patches, which must not +be compressed). For example, from <c>app-admin/showconsole</c>: </p> <codesample lang="ebuild"> -src_unpack() { - unpack ${A} - cd "${S}" - epatch "${WORKDIR}/${P}-suse-update.patch.bz2" - epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch" -} -</codesample> -<p>As stated before, if you are using EAPI >=2, you should apply the patches in the <uri link="::ebuild-writing/functions/src_prepare">src_prepare</uri> function</p> -<codesample lang="ebuild"> src_prepare() { epatch "${WORKDIR}/${P}-suse-update.patch.bz2" epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch" @@ -64,20 +112,6 @@ src_prepare() { Remember to add the patch to <c>SRC_URI</c>. </p> </body> - -<subsection> -<title>CVS Keyword Lines and Patches</title> -<body> -<p> -If your patch includes any changes to CVS <c>$Id: $</c> -(or <c>$Header: $</c>, or <c>$Date: $</c>) lines, it cannot be -distributed under <c>files/</c>, since CVS will clobber the patch when -you commit. In these situations, either remove this hunk of the patch -manually, or mirror the file. -</p> -</body> -</subsection> - </section> <section> @@ -95,11 +129,9 @@ A simple example: </p> <codesample lang="ebuild"> -src_unpack() { - unpack ${A} - cd "${S}" - EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \ - EPATCH_FORCE="yes" epatch +src_prepare() { + EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \ + EPATCH_FORCE="yes" epatch } </codesample> diff --git a/ebuild-writing/functions/src_prepare/text.xml b/ebuild-writing/functions/src_prepare/text.xml index 29b1588..b7c1b9a 100644 --- a/ebuild-writing/functions/src_prepare/text.xml +++ b/ebuild-writing/functions/src_prepare/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_prepare/"> <chapter> <title>src_prepare</title> @@ -31,15 +31,38 @@ <section> <title>Default <c>src_prepare</c></title> <body> + <p> -Starting from EAPI="2", the src_prepare function is the appropriate area to perform -any kind of patching and source code manipulation, instead of src_unpack. +Before EAPI 6, the default implementation did nothing: </p> + <codesample lang="ebuild"> src_prepare() { - true; + true } </codesample> + +<p> +Beginning with EAPI 6, the src_prepare function gained a new default +implementation: +</p> + +<codesample lang="ebuild"> +src_prepare() { + if [[ $(declare -p PATCHES 2>/dev/null) == "declare -a"* ]]; then + [[ -n ${PATCHES[@]} ]] && eapply "${PATCHES[@]}" + else + [[ -n ${PATCHES} ]] && eapply ${PATCHES} + fi + eapply_user +} +</codesample> + +<note> +With EAPI 6, you must call <c>eapply_user</c> or <c>default</c> if you define +<c>src_prepare</c>! +</note> + </body> </section> @@ -48,15 +71,29 @@ src_prepare() { <body> <codesample lang="ebuild"> src_prepare() { - epatch "${FILESDIR}/${PV}/${P}-fix-bogosity.patch" - use pam && epatch "${FILESDIR}/${PV}/${P}-pam.patch" + eapply "${FILESDIR}/${PV}/${P}-fix-bogosity.patch" + eapply "${FILESDIR}/${PV}/${P}-pam.patch" + + eapply_user - sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!" + sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!" } </codesample> </body> </section> +<section> +<title><c>src_prepare</c> Processes</title> +<body> +<p> +The following subsections cover different topics which often occur +when writing <c>src_prepare</c> functions. +</p> + +<contentsTree/> +</body> +</section> + </chapter> <include href="epatch/"/> <include href="autopackage/"/> diff --git a/ebuild-writing/functions/src_test/text.xml b/ebuild-writing/functions/src_test/text.xml index dd02d4b..04d180c 100644 --- a/ebuild-writing/functions/src_test/text.xml +++ b/ebuild-writing/functions/src_test/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_test/"> <chapter> <title>src_test</title> @@ -31,23 +31,13 @@ <section> <title>Default <c>src_test</c></title> <body> -<p> From sys-apps/portage-2.1.2.9 </p> +<p>The default test phase in EAPI 6 is equivalent to the following:</p> <codesample lang="ebuild"> src_test() { - if emake -j1 check -n &> /dev/null; then - vecho ">>> Test phase [check]: ${CATEGORY}/${PF}" - if ! emake -j1 check; then - hasq test $FEATURES && die "Make check failed. See above for details." - hasq test $FEATURES || eerror "Make check failed. See above for details." - fi - elif emake -j1 test -n &> /dev/null; then - vecho ">>> Test phase [test]: ${CATEGORY}/${PF}" - if ! emake -j1 test; then - hasq test $FEATURES && die "Make test failed. See above for details." - hasq test $FEATURES || eerror "Make test failed. See above for details." - fi - else - vecho ">>> Test phase [none]: ${CATEGORY}/${PF}" + if nonfatal emake check -n &> /dev/null; then + emake check + elif nonfatal emake test -n &> /dev/null; then + emake test fi } </codesample> @@ -59,34 +49,52 @@ src_test() { <body> <codesample lang="ebuild"> src_test() { - cd "${S}"/src/testdir + cd "${S}"/src/testdir || die - # Test 49 won't work inside a portage environment - sed -i -e 's~test49.out~~g' Makefile + # Test 49 won't work inside a Portage environment + sed -i -e 's~test49.out~~g' Makefile || die - # Try to run the non-gui tests only - make test-nongui \ - || die "At least one test failed" + # Try to run the non-gui tests only + # pass -j1 if tests do not support being run in parallel + emake -j1 test-nongui } </codesample> </body> </section> <section> -<title>Common <c>src_test</c> Tasks</title> +<title>Supporting test suites in packages</title> <body> + +<p> +If the packaged software is equipped with a test suite, it is sensible +to run it. Sometimes the package will need additional dependencies for this, +i.e., dependencies that are only required to run the test suite. Such test-only +dependencies should be specified in DEPEND or BDEPEND behind a USE flag; +often, the <c>test</c> USE flag will be used for this. Please refer to the +section on <uri link="::general-concepts/dependencies/#Test Dependencies"/> +for more information. +</p> + +<p> +Note that the <c>test</c> USE flag is only necessary if there are +test dependencies, tests are being built conditionally, or it is desirable +to vary behaviour based on whether tests will be run (e.g. downloading large +files in SRC_URI). It is not appropriate to use the flag to simply indicate that +tests exist and are expected to pass. +</p> + <p> Often the default <c>src_test</c> is fine. Sometimes it is necessary to remove certain tests from the list if they cannot be used with a -portage environment. Reasons for such a failure could include: +Portage environment. Reasons for such a failure could include: </p> <ul> - <li>Needing to use X.</li> <li> Needing to work with files which are disallowed by the sandbox. </li> - <li>Requiring user input (src_test must not be interactive).</li> + <li>Requiring user input (<c>src_test</c> must not be interactive).</li> <li>Requiring root privileges.</li> </ul> @@ -96,45 +104,172 @@ using <c>sed</c> or skipping a particular <c>make</c> target is sufficient. </p> +<p> +Try to ensure that tests work properly for your ebuild. A good test +suite is extremely helpful for arch maintainers. +Sometimes it is necessary to skip tests entirely. This can be done by +setting <c>RESTRICT="test"</c> in the ebuild. +</p> + <note> -<c>emake</c> should not be used for <c>src_test</c> <d/> trying to -parallelise tests unless the <c>Makefile</c> was specifically designed -for this can cause all sorts of strange problems. +If upstream provides a test suite that doesn't work, consider talking +to them about getting it fixed. A broken test suite requires developers +to investigate each test failure in order to determine whether it is +genuine or indicates a broken test. </note> +</body> +</section> +<section> +<title>Tests that require network or service access</title> +<body> <p> -Try to ensure that tests work properly for your ebuild. A good test -suite is extremely helpful for arch maintainers. +Sometimes test suites (and other build-time programs) attempt to use +remote or local network, or production servers running on the host. All +of these are strictly forbidden. Developers should either fix such tests +to work in an isolated environment, or disable them completely unless +explicitly allowed by the user. At the bare minimum, the tests must +not fail with <c>FEATURES=network-sandbox</c> being enabled. +</p> + +<p> +Internet access within the build procedure is forbidden for +the following reasons: +</p> +<ul> + <li> + the build may be running in an environment with no or restricted + Internet access, and this must not cause the tests (build) to fail; + </li> + + <li> + the Internet connection may be unstable (e.g. poor reception) + in which case an interrupted connection or packet loss must not + cause the tests to fail or hang, and it should not cause unnecessary + delays; + </li> + + <li> + the Internet connection may be running on a limited data plan + in which case the additional network use may cause additional + charges or other inconveniences to the user; + </li> + + <li> + the remote network services used by the tests may become unavailable + temporarily or permanently, causing unexpected test failures; + </li> + + <li> + accessing remote sites always poses a privacy issue, and possibly + a threat to security (e.g. through inadvertently exposing + information about the system). + </li> +</ul> + +<p> +Fixing tests that require Internet access usually requires cooperation +with upstream, and porting the tests to use test techniques such as +mocking or using replay data. For this reason, developers report +the issue upstream and skip tests that require network access. +It is recommended to explicitly leave a note as to why the tests are +skipped, so that other developers can re-enable them locally to run +a more complete test suite. +</p> + +<p> +It is generally considered acceptable to rely on IPv4 <c>localhost</c> being +resolvable and available for binding. Tests should only connect to services +that are started as part of the testsuite. It is not acceptable to connect +to daemons run outside the test environment. +</p> + +<p> +Local server access within the build procedure is forbidden for the following +reasons: +</p> + +<ul> + <li> + tests must run reliably independently of whether a particular + server is running throughout the build process or not, + </li> + + <li> + using production services for running tests is extremely + <b>dangerous</b> as it may inadvertently expose bugs in those + services, causing instability, data loss or even exposing security + vulnerabilities. + </li> +</ul> + +<p> +Fixing tests that require access to local services is usually done +via starting additional isolated instances of those services during +the test phase. Those services must either be running on a UNIX +socket or on the loopback interface, to reliably prevent remote access. +</p> + +<p> +For all networked services exposed during the test phase (either by +the ebuild or the tests themselves), UNIX sockets are strongly preferred +over IP sockets as they provide better means for unique naming +and access control mechanisms. IP sockets can be subject to port +collisions with other local services and they can be accessed by local +system users who may exploit a vulnerability through the tests. +</p> + +<p> +Additional protection against those issues is provided through +<c>FEATURES=network-sandbox</c>. However, this is only an optional +Portage feature relying on specific Linux kernel namespace mechanisms +and developers should not rely on it being enabled. </p> </body> </section> <section> -<title>Skipping Tests</title> +<title>Tests that require X11</title> <body> <p> -Sometimes it is necessary to skip tests entirely. This can be done -using a dummy <c>src_test</c> function: +Some packages include tests (or other build-time applications) that +attempt to use the user's X11 session and fail being unable to connect +to it. Those tests need to be fixed to work independently of the X11 +server that might or might not be running when packages are being built. +</p> + +<p> +If the program in question does not strictly need X11 but merely +attempts to take opportunity of the <c>DISPLAY</c> variable being set, +the best solution is to simply unset this variable in the ebuild. </p> <codesample lang="ebuild"> src_test() { - # Tests don't even remotely work inside portage - true + # tests attempt to connect to X11 and fail when it is set + # however, they work just fine without X11 + unset DISPLAY + + default } </codesample> <p> -Another option would be to set <c>RESTRICT="test"</c> in the ebuild. +If the package actually requires a running X11 server to run +the complete test suite, you can use the <c>virtualx</c> eclass to +provide an isolated Xvfb environment for the tests to use. It provides +a virtual X11 display that is not connected to any physical device +and that programs can use reliably. </p> -<note> -If upstream provide a test suite which doesn't work, consider talking -to them about getting it fixed. A broken test suite is worse than no -test suite at all, since we are unable to tell whether a test failure -indicates a genuine fault. -</note> +<codesample lang="ebuild"> +inherit virtualx + +src_test() { + virtx default +} +</codesample> </body> </section> diff --git a/ebuild-writing/functions/src_unpack/cvs-sources/text.xml b/ebuild-writing/functions/src_unpack/cvs-sources/text.xml deleted file mode 100644 index 2f24cc7..0000000 --- a/ebuild-writing/functions/src_unpack/cvs-sources/text.xml +++ /dev/null @@ -1,190 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/cvs-sources/"> -<chapter> -<title>CVS Sources</title> - -<body> -<p> -Rather than working with a source tarball, it is possible to use -upstream's CVS server directly. This can be useful when there is a -need to test unreleased snapshots on a regular basis. -</p> -</body> - -<section> -<title>Disadvantages of CVS Sources</title> -<body> - -<p> -Note that CVS ebuilds should <b>not</b> generally be added to the tree -for the following reasons: -</p> - -<ul> - <li> - Upstream CVS servers tend to be far less reliable than our mirroring - system. - </li> - <li> - CVS ebuilds create a very heavy server load <d/> not only is CVS not - mirrored, but allowing a CVS checkout is considerably more work for - a server than simply serving up a file via HTTP or FTP. - </li> - <li> - Many users who are behind strict firewalls cannot use CVS. - </li> -</ul> - -<p> -It is safer to make a snapshot instead. For example, vim snapshots are made using: -</p> - -<pre> -$ cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vim export -r HEAD vim -</pre> -</body> -</section> - -<section> -<title>Disadvantages of CVS Live Sources</title> -<body> - -<p> -CVS ebuilds which work against CVS <c>HEAD</c> rather than a specific -date or revision are even worse candidates for tree inclusion: -</p> - -<ul> - <li> - You can never be sure whether upstream's CVS will actually - build at any given point; which will most likely cause QA issues. - </li> - <li> - It is extremely difficult to track down bugs when you cannot install - the same version of a package as the reporter. - </li> - <li> - Many upstream package maintainers tend to get upset if people aren't - using a specific released version. - </li> -</ul> - -</body> -</section> - -<section> -<title>Using CVS Sources</title> -<body> - -<note> -CVS ebuilds must be either with empty <c>KEYWORDS</c> or -package.masked (but <e>not</e> both). Empty <c>KEYWORDS</c> are -strongly preferred. This applies to "live" ebuilds (<c>-9999</c>) and -to ebuilds that extract a static revision but still use CVS for -fetching. -</note> - -<p> -To use a CVS source, <c>cvs.eclass</c> must be inherited, and then a -number of variables must be set. The following variables are often -useful: -</p> - -<table> - <tr> - <th>Variable</th> - <th>Purpose</th> - <th>Example</th> - </tr> - <tr> - <ti><c>ECVS_SERVER</c></ti> - <ti>Server and path</ti> - <ti><c>"cvs.sourceforge.net:/cvsroot/vim"</c></ti> - </tr> - <tr> - <ti><c>ECVS_MODULE</c></ti> - <ti>Module</ti> - <ti><c>"vim"</c></ti> - </tr> - <tr> - <ti><c>ECVS_BRANCH</c></ti> - <ti>Branch</ti> - <ti><c>"HEAD"</c></ti> - </tr> - <tr> - <ti><c>ECVS_AUTH</c></ti> - <ti>Auth method</ti> - <ti><c>"ext"</c></ti> - </tr> - <tr> - <ti><c>ECVS_USER</c></ti> - <ti>Username</ti> - <ti><c>"anoncvs"</c></ti> - </tr> - <tr> - <ti><c>ECVS_PASS</c></ti> - <ti>Password</ti> - <ti><c>""</c></ti> - </tr> - <tr> - <ti><c>ECVS_TOPDIR</c></ti> - <ti>Unpack location</ti> - <ti><c>"${DISTDIR}/cvs-src/${ECVS_MODULE}"</c></ti> - </tr> -</table> - -<p> -See the eclass itself for the full range of options. To perform the -actual checkout, use the <c>cvs_src_unpack</c> function. -</p> - -<p> -Here's a simple example, based upon the CVS options in vim.eclass: -</p> - -<codesample lang="ebuild"> -inherit cvs - -SRC_URI="" - -src_unpack() { - ECVS_SERVER="cvs.sourceforge.net:/cvsroot/vim" - ECVS_USER="anonymous" - ECVS_PASS="" - ECVS_AUTH="pserver" - if [[ $(get_major_version ) -ge 7 ]] ; then - ECVS_MODULE="vim7" - else - ECVS_MODULE="vim" - fi - ECVS_TOP_DIR="${DISTDIR}/cvs-src/${ECVS_MODULE}" - cvs_src_unpack -} -</codesample> - -<p> -Here's another approach, based upon the <c>emacs-cvs</c> ebuild, which -relies upon the default <c>src_unpack</c> provided in the eclass; this -approach is simpler but less flexible: -</p> - -<codesample lang="ebuild"> -inherit cvs - -ECVS_AUTH="ext" -CVS_RSH="ssh" -ECVS_SERVER="savannah.gnu.org:/cvsroot/emacs" -ECVS_MODULE="emacs" -ECVS_BRANCH="emacs-unicode-2" -ECVS_USER="anoncvs" -ECVS_PASS="" -ECVS_CVS_OPTIONS="-dP" - -# ...and so on. No src_unpack() is specified. -</codesample> - -</body> -</section> - -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/deb-sources/text.xml b/ebuild-writing/functions/src_unpack/deb-sources/text.xml deleted file mode 100644 index bdbadb4..0000000 --- a/ebuild-writing/functions/src_unpack/deb-sources/text.xml +++ /dev/null @@ -1,12 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/deb-sources/"> -<chapter> -<title>Debian Sources</title> - -<body> -<todo> -from vapier: we dont have to 'handle' these because all debian packages have a source tarball ... the .deb format is pretty simple though, it's managed by the 'ar' utility from binutils. you can unpack a .deb by simply doing ar x blah.deb ... this will give you three files: debian-binary: plain text file which just contains version number of the .deb format control.tar.gz: a few files which control installing/verifying of package data.tar.gz: all the compiled files ... you could just extract it to / -</todo> -</body> -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/other-formats/text.xml b/ebuild-writing/functions/src_unpack/other-formats/text.xml index 3647c80..809802b 100644 --- a/ebuild-writing/functions/src_unpack/other-formats/text.xml +++ b/ebuild-writing/functions/src_unpack/other-formats/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_unpack/other-formats/"> <chapter> <title>Other Archive Formats</title> @@ -19,7 +19,7 @@ If a package is supplied as a .zip file, you should: </p> <ul> - <li><c>DEPEND</c> upon <c>app-arch/unzip</c></li> + <li><c>BDEPEND</c> upon <c>app-arch/unzip</c></li> <li>Use <c>unpack</c> as normal</li> </ul> diff --git a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml index dcf9113..5d3a6be 100644 --- a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml +++ b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_unpack/rpm-sources/"> <chapter> <title>RPM Sources</title> @@ -19,16 +19,16 @@ that will unpack the RPM files. </p> <p> -If you do need to apply patches then override <c>src_unpack</c> in a +If you do need to call additional unpack functions then override <c>src_unpack</c> in a manner such as: </p> <codesample lang="ebuild"> -src_unpack () { - rpm_src_unpack ${A} - cd "${S}" +src_unpack() { + rpm_src_unpack ${A} + cd "${S}" - use ssl && epatch "${FILESDIR}/${PV}/${P}-ssl.patch" + use ssl && eapply "${FILESDIR}/${PV}/${P}-ssl.patch" } </codesample> @@ -52,18 +52,20 @@ patches. The filename should be <c>suse-fetchmail-6.2.5.54.1.ebuild</c>. </p> <codesample lang="ebuild"> -# Copyright 1999-2005 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -inherit eutils versionator rpm +EAPI=7 + +inherit rpm -MY_PV=$(replace_version_separator 3 '-') +MY_PV=$(ver_rs 3 '-') MY_P=fetchmail-${MY_PV} -SRC_URI="http://suse.osuosl.org/suse/i386/9.2/suse/src/${MY_P}.src.rpm" DESCRIPTION="SuSE 9.2 Fetchmail Source Package" -HOMEPAGE="http://www.suse.com" +HOMEPAGE="https://www.suse.com" +SRC_URI="https://suse.osuosl.org/suse/i386/9.2/suse/src/${MY_P}.src.rpm" +S=${WORKDIR}/fetchmail-$(ver_cut 1-3) LICENSE="GPL-2 public-domain" SLOT="0" @@ -74,20 +76,22 @@ RESTRICT="mirror" # Need to test if the file can be unpacked with rpmoffset and cpio # If it can't then set: -#DEPEND="app-arch/rpm" +#BDEPEND="app-arch/rpm" # To force the use of rpmoffset and cpio instead of rpm2cpio from # app-arch/rpm, then set the following: #USE_RPMOFFSET_ONLY=1 -S=${WORKDIR}/fetchmail-$(get_version_component_range 1-3) - -src_unpack () { +src_unpack() { rpm_src_unpack ${A} - cd "${S}" - EPATCH_SOURCE="${WORKDIR}" EPATCH_SUFFIX="patch" \ - EPATCH_FORCE="yes" epatch +} + +src_prepare() { + for i in "${WORKDIR}"/*.patch ; do + eapply "${i}" + done + eapply_user } </codesample> diff --git a/ebuild-writing/functions/src_unpack/svn-sources/text.xml b/ebuild-writing/functions/src_unpack/svn-sources/text.xml deleted file mode 100644 index e436c97..0000000 --- a/ebuild-writing/functions/src_unpack/svn-sources/text.xml +++ /dev/null @@ -1,116 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/svn-sources/"> -<chapter> -<title>Subversion Sources</title> - -<body> -<p> -As with CVS, an eclass exists for working directly with upstream -Subversion repositories. See <uri link="::eclass-reference/subversion.eclass/">subversion.eclass</uri> -for a full list of functions and variables. Also see -the <uri link="::ebuild-writing/functions/src_unpack/cvs-sources"/> -ection. -</p> -</body> - -<section> -<title>Disadvantages of Subversion Sources</title> -<body> - -<p> -Note that Subversion ebuilds should <b>not</b> generally be added to -the tree for much the same reasons that live CVS ebuilds should not (see -<uri link="::ebuild-writing/functions/src_unpack/cvs-sources#Disadvantages of CVS Sources"/>). -Indeed, there should be even less impetus to add a live Subversion ebuild than a live CVS ebuild, as -Subversion checkouts are roughly a factor of five larger than an -equivalent CVS checkout. -</p> - -<p> -It is safer (and better for the user) to make a snapshot instead. For -example, <c>gentoo-syntax</c> snapshots could be made using: -</p> - -<pre> -$ svn export svn://svn.berlios.de/svnroot/repos/gentoo-syntax -r HEAD gentoo-syntax -</pre> -</body> -</section> - -<section> -<title>Using Subversion Sources</title> -<body> - -<note> -Subversion ebuilds must be either with empty <c>KEYWORDS</c> or -package.masked (but <e>not</e> both). Empty <c>KEYWORDS</c> are -strongly preferred. This applies to "live" ebuilds (<c>-9999</c>) and -to ebuilds that extract a static revision but still use Subversion for -fetching. -</note> - -<p> -To use a Subversion source, <c>subversion.eclass</c> must be -inherited, and then at least <c>ESVN_REPO_URI</c> must be set. The -following variables are also noteworthy: -</p> - -<table> - <tr> - <th>Variable</th> - <th>Purpose</th> - <th>Example</th> - </tr> - <tr> - <ti><c>ESVN_REPO_URI</c></ti> - <ti>Server and path (http, https, svn)</ti> - <ti><c>"svn://svn.example.com/foobar/trunk"</c></ti> - </tr> - <tr> - <ti><c>ESVN_STORE_DIR</c></ti> - <ti>Unpack location</ti> - <ti><c>ESVN_STORE_DIR="${DISTDIR}/svn-src"</c></ti> - </tr> - <tr> - <ti><c>ESVN_PROJECT</c></ti> - <ti>Project name of ebuild</ti> - <ti><c>ESVN_PROJECT="${PN/-svn}"</c></ti> - </tr> - <tr> - <ti><c>ESVN_BOOTSTRAP</c></ti> - <ti>Bootstrap command or script</ti> - <ti><c>ESVN_BOOTSTRAP="autogen.sh"</c></ti> - </tr> - <tr> - <ti><c>ESVN_PATCHES</c></ti> - <ti>Patches to apply during bootstrap</ti> - <ti><c>ESVN_PATCHES="${FILESDIR}/*.patch"</c></ti> - </tr> -</table> - -<p> -See the eclass itself and <uri link="::eclass-reference/subversion.eclass/">subversion.eclass</uri> -for the full range of options. To perform the actual checkout, use -the <c>subversion_src_unpack</c> function, which calls -both <c>subversion_svn_fetch</c> and <c>subversion_bootstrap</c> -itself. -</p> - -<p> -Here is a simple example, based upon the Subversion options in -<c>litu-svn-20040902.ebuild</c>; this approach is sufficient for most -Subversion ebuilds: -</p> - -<codesample lang="ebuild"> -inherit subversion - -ESVN_REPO_URI="http://tao.uab.es/ion/svn/libtu/trunk" -ESVN_PROJECT="libtu-snapshot" -</codesample> - -</body> -</section> - -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/text.xml b/ebuild-writing/functions/src_unpack/text.xml index 542b3fb..045e1c9 100644 --- a/ebuild-writing/functions/src_unpack/text.xml +++ b/ebuild-writing/functions/src_unpack/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_unpack/"> <chapter> <title>src_unpack</title> @@ -11,7 +11,7 @@ </tr> <tr> <th>Purpose</th> - <ti>Extract source packages and do any necessary patching or fixes.</ti> + <ti>Extract source packages.</ti> </tr> <tr> <th>Sandbox</th> @@ -33,9 +33,9 @@ <body> <codesample lang="ebuild"> src_unpack() { - if [ "${A}" != "" ]; then - unpack ${A} - fi + if [[ -n ${A} ]]; then + unpack ${A} + fi } </codesample> </body> @@ -44,20 +44,13 @@ src_unpack() { <section> <title>Sample <c>src_unpack</c></title> <body> + <codesample lang="ebuild"> src_unpack() { - unpack ${A} - cd "${S}" - - epatch "${FILESDIR}/${PV}/${P}-fix-bogosity.patch" - use pam && epatch "${FILESDIR}/${PV}/${P}-pam.patch" - - sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!" + unpack ${P}.tar.xz + use foo && unpack ${P}-foo-extension.tar.xz } </codesample> -<note> -When using EAPI >=2, you should use the <uri link="::ebuild-writing/functions/src_prepare">src_prepare</uri> function to apply patches or alter any of the source files, instead of the src_unpack. -</note> </body> </section> @@ -80,6 +73,42 @@ usually simpler to avoid working with <c>${A}</c>. </section> <section> +<title>Known file formats</title> +<body> + +<p> +The <c>unpack</c> function recognizes the following file formats: +</p> + +<ul> + <li><c>*.tar</c></li> + <li> + <c>*.gz</c>, <c>*.Z</c>, + <c>*.tar.gz</c>, <c>*.tgz</c>, <c>*.tar.Z</c> + </li> + <li> + <c>*.bz2</c>, <c>*.bz</c>, + <c>*.tar.bz2</c>, <c>*.tbz2</c>, <c>*.tar.bz</c>, <c>*.tbz</c> + </li> + <li><c>*.lzma</c>, <c>*.tar.lzma</c></li> + <li><c>*.xz</c>, <c>*.tar.xz</c>, <c>*.txz</c></li> + <li><c>*.zip</c>, <c>*.ZIP</c>, <c>*.jar</c></li> + <li><c>*.a</c>, <c>*.deb</c></li> +</ul> + +<p> +In EAPI 6 and later, filename extensions are matched case-insensitively. +</p> + +<important> +Unless the utility needed for unpacking is in the system set, the ebuild must +specify the necessary build time dependency (<c>BDEPEND</c>) for it. +</important> + +</body> +</section> + +<section> <title><c>src_unpack</c> Actions</title> <body> <p> @@ -93,10 +122,7 @@ The following subsections cover different topics which often occur when writing </chapter> -<include href="cvs-sources/"/> -<include href="svn-sources/"/> -<include href="tla-sources/"/> +<include href="vcs-sources/"/> <include href="rpm-sources/"/> -<include href="deb-sources/"/> <include href="other-formats/"/> </guide> diff --git a/ebuild-writing/functions/src_unpack/tla-sources/text.xml b/ebuild-writing/functions/src_unpack/tla-sources/text.xml deleted file mode 100644 index 97a8b40..0000000 --- a/ebuild-writing/functions/src_unpack/tla-sources/text.xml +++ /dev/null @@ -1,12 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/tla-sources/"> -<chapter> -<title>Arch Sources</title> - -<body> -<todo> -Anyone want to write this? You can probably mostly copy the CVS Sources and Subversion Sources chapters. -</todo> -</body> -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/vcs-sources/text.xml b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml new file mode 100644 index 0000000..0596fef --- /dev/null +++ b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml @@ -0,0 +1,100 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-writing/functions/src_unpack/vcs-sources/"> +<chapter> +<title>Version Control System (VCS) Sources</title> +<body> + +<p> +Rather than working with a source tarball, it is possible to use upstream +source code repositories directly. This can be useful when there is a need to +test unreleased snapshots on a regular basis. A number of eclasses exists for +this purpose; see their documentation for a list of available functions and +variables. +</p> + +<ul> + <li><uri link="::eclass-reference/cvs.eclass/"/></li> + <li><uri link="::eclass-reference/darcs.eclass/"/></li> + <li><uri link="::eclass-reference/git-r3.eclass/"/></li> + <li><uri link="::eclass-reference/mercurial.eclass/"/></li> + <li><uri link="::eclass-reference/subversion.eclass/"/></li> +</ul> + +<note> +VCS ebuilds must be with empty <c>KEYWORDS</c> but <e>not</e> package.masked +(except if the mask is for an independent reason). Usually the <c>KEYWORDS</c> +line should be omitted altogether. This applies to "live" ebuilds (<c>-9999</c>) +and to ebuilds that extract a static revision but still use a version control +system for fetching. +</note> + +</body> + +<section> +<title>Disadvantages of VCS Sources</title> +<body> + +<p> +Note that VCS ebuilds should <b>not</b> generally be added to the tree for the +following reasons: +</p> + +<ul> + <li> + Upstream VCS servers tend to be far less reliable than our mirroring + system. + </li> + <li> + VCS ebuilds create a very heavy server load <d/> not only are repositories + not mirrored, but fetching sources from them is considerably more work for + a server than simply serving up a file via HTTP or FTP. + </li> + <li> + Local copies of a repository are several times larger than a tarball of the + same sources, and tend to grow over time because they include the history. + </li> + <li> + Many users who are behind strict firewalls cannot use protocols like CVS. + </li> +</ul> + +<p> +It is safer (and better for the user) to make a snapshot instead. For example, +<c>app-editors/emacs</c> snapshots are made using: +</p> + +<pre> +$ git archive --prefix=emacs/ HEAD | xz > emacs-${PV}.tar.xz +</pre> + +</body> +</section> + +<section> +<title>Disadvantages of VCS Live Sources</title> +<body> + +<p> +VCS ebuilds that work against the latest head (or tip) rather than a specific +date or revision are even worse candidates for tree inclusion: +</p> + +<ul> + <li> + You can never be sure whether upstream's source will actually build at any + given point; which will most likely cause QA issues. + </li> + <li> + It is extremely difficult to track down bugs when you cannot install the + same version of a package as the reporter. + </li> + <li> + Many upstream package maintainers tend to get upset if people aren't using + a specific released version. + </li> +</ul> + +</body> +</section> +</chapter> +</guide> diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml index d10a51f..47babef 100644 --- a/ebuild-writing/functions/text.xml +++ b/ebuild-writing/functions/text.xml @@ -1,20 +1,38 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/"> <chapter> -<title>Ebuild Functions</title> +<title>Ebuild Phase Functions</title> <body> <p> -When installing packages from source, the function call order is <c>pkg_setup</c>, -<c>src_unpack</c>, <c>src_prepare</c>, <c>src_compile</c>, <c>src_test</c> (optional, <c>FEATURES="test"</c>), -<c>src_install</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. When installing packages -from a binary, the function call order is <c>pkg_setup</c>, <c>pkg_preinst</c>, -<c>pkg_postinst</c>. -As some phases haven't been introduced from the beginning, you can have a look at -<uri link="::ebuild-writing/eapi"/> for an overview, what have been introduced in which EAPI. +When installing packages from source, the phase function call order is +<c>pkg_pretend</c>, <c>pkg_setup</c>, +<c>src_unpack</c>, <c>src_prepare</c>, <c>src_configure</c>, <c>src_compile</c>, +<c>src_test</c> (optional, <c>FEATURES="test"</c>), +<c>src_install</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. When installing +packages from a binary, the phase function call order is <c>pkg_pretend</c>, +<c>pkg_setup</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. +As some phases haven't been introduced from the beginning, you can have a look +at <uri link="::ebuild-writing/eapi/"/> for an overview, what have been +introduced in which EAPI. </p> -<figure short="How the ebuild functions are processed" link="diagram.png"/> +<p> +Ebuilds should usually define phases in the order they are called, +as set out above, for readability. +</p> + +<figure short="How the ebuild phase functions are processed" link="diagram.png"/> + +<p> +The <c>pkg_pretend</c> function is to be used for performing various +early sanity checks, such as ensuring that certain kernel options are +enabled. It is important to keep in mind that <c>pkg_pretend</c> runs +separately from the rest of the phase function sequence. Consequently, +there is no environment saving or propagation to the next +phase. Moreover, ebuild dependencies are not guaranteed to be +satisfied at this phase. +</p> <p> The <c>pkg_prerm</c> and <c>pkg_postrm</c> functions are called when uninstalling a @@ -31,8 +49,9 @@ location, and Portage records digests of the files installed. </p> <p> -When testing or debugging, you can instruct Portage to execute a specific function -from an ebuild by using the <c>ebuild</c> command, see the <c>ebuild(1)</c> manual +When testing or debugging, you can instruct Portage to execute a +specific phase function of an ebuild by using the <c>ebuild</c> +command, see the <c>ebuild(1)</c> manual page for further information. </p> @@ -41,14 +60,51 @@ Downloading a package's source happens before any of these phases, so <c>emerge --fetchonly</c> should perform all the network access you need (unless you're using live ebuilds). Network access outside of this would not be cached locally (e.g. in <c>${DISTDIR}</c>, see -<uri link="::ebuild-writing/variables#Predefined Read-Only Variables."/>), +<uri link="::ebuild-writing/variables/#Predefined Read-Only Variables"/>), which makes it hard to have reproducible builds (see -<uri link="::ebuild-writing/functions/src_unpack/cvs-sources#Disadvantages of CVS Sources"/>). +<uri link="::ebuild-writing/functions/src_unpack/vcs-sources/#Disadvantages of VCS Sources"/>). Avoid network access in any phase by using local files, extending <c>SRC_URI</c> (see -<uri link="::ebuild-writing/variables#Ebuild-defined Variables"/>), etc. +<uri link="::ebuild-writing/variables/#Ebuild-defined Variables"/>), etc. +</p> +</body> + +<section> +<title>Default phase functions</title> +<body> + +<p> +The default <c>pkg_nofetch</c> and <c>src_*</c> phase functions are accessible +via a function having a name that begins with <c>default_</c> and ends with the +respective phase function name. For example, a call to a function with the name +<c>default_src_compile</c> is equivalent to a call to the default +<c>src_compile</c> implementation. +</p> + +<p> +The default phase functions are: </p> + +<ul> + <li><c>default_pkg_nofetch</c></li> + <li><c>default_src_unpack</c></li> + <li><c>default_src_prepare</c></li> + <li><c>default_src_configure</c></li> + <li><c>default_src_compile</c></li> + <li><c>default_src_test</c></li> + <li><c>default_src_install</c></li> +</ul> + +<p> +A function named <c>default</c> is redefined for each of the above phases, +so that it will call the <c>default_*</c> function corresponding to +the current phase. For example, a call to the <c>default</c> function +during the <c>src_compile</c> phase is equivalent to a call to the +<c>default_src_compile</c> function. +</p> + </body> +</section> <section> <title>Contents</title> diff --git a/ebuild-writing/messages/text.xml b/ebuild-writing/messages/text.xml index 1012edf..bfe666c 100644 --- a/ebuild-writing/messages/text.xml +++ b/ebuild-writing/messages/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/messages/"> <chapter> <title>Messages</title> @@ -45,9 +45,9 @@ with a green asterisk. On earlier versions, elog behaves just like einfo. <codesample lang="ebuild"> pkg_postinst() { - elog "You will need to set up your /etc/foo/foo.conf file before" - elog "running foo for the first time. For details, please see the" - elog "foo.conf(5) manual page." + elog "You will need to set up your /etc/foo/foo.conf file before" + elog "running foo for the first time. For details, please see the" + elog "foo.conf(5) manual page." } </codesample> @@ -61,8 +61,8 @@ logged by default. <codesample lang="ebuild"> src_compile() { - einfo "Starting a silent compile that takes hours." - ./build + einfo "Starting a silent compile that takes hours." + ./build || die } </codesample> @@ -100,7 +100,7 @@ is mainly used for displaying additional error details before bailing out. <p> The <c>eqawarn</c> function can be used by eclass authors to notify ebuild writers about - deprecated functionality. eqawarn is defined in eutils. Portage doesn't log the qa message + deprecated functionality. eqawarn is defined in eutils prior to EAPI=7. Portage doesn't log the qa message class by default so users don't get annoyed by seeing messages they can't do much about. </p> @@ -129,7 +129,7 @@ Here is an example of a bad message: <codesample lang="ebuild"> i=10 while ((i--)) ; do - ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass" + ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass" done </codesample> diff --git a/ebuild-writing/misc-files/changelog/text.xml b/ebuild-writing/misc-files/changelog/text.xml deleted file mode 100644 index 7ee5ce7..0000000 --- a/ebuild-writing/misc-files/changelog/text.xml +++ /dev/null @@ -1,111 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/misc-files/changelog/"> -<chapter> -<title>ChangeLog</title> - -<body> -<p> -The <c>ChangeLog</c> must be updated with each commit. The -<uri link="::tools-reference/echangelog/">echangelog tool</uri> should be used to create <c>ChangeLog</c> entries; -the format of a <c>ChangeLog</c> is now defined as "whatever -<c>echangelog</c> creates". -</p> - -<p> -You should include references to any relevant bugs. The standard -format for doing this is via the phrase <c>bug #20600</c> — this -format (with the hash sign included) is recognised via -<uri link="http://packages.gentoo.org">packages.gentoo.org</uri> and -similar tools. When including user-submitted ebuilds or patches, you -should credit the user with their full name and email address (or -whatever they use to identify themselves on bugzilla <d/> some users -prefer to be known only by a nickname). -</p> - -<p> -If you are changing keywords, make sure you clearly state what -keywords you add or remove. "Marked stable" is a nuisance for -architecture teams, even if there was only one keyword in the ebuild -at the time. "Stable on all archs" isn't generally any better (and -should you really be stabling on all archs?) — do you mean "all", or -"all the ones that are currently keyworded"? A list like "x86 sparc -mips" is much more useful. -</p> - -<p> -A typical <c>ChangeLog</c> snippet might look like the following: -</p> - -<pre> - *vim-6.3.068 (25 Mar 2005) - - 25 Mar 2005; Ciaran McCreesh <ciaranm@gentoo.org> +vim-6.3.068.ebuild: - New release. Fixes bug #79981, bug #81289, bug #83383, bug #83416, bug - #83565, bug #85758, upstream patches up to 6.3.068. - - 22 Mar 2005; Aron Griffis <agriffis@gentoo.org> vim-6.3-r4.ebuild: - Stable on alpha -</pre> - -<note> -If a <c>ChangeLog</c> file is not present in your current working directory, -then you should write a <c>ChangeLog</c> entry in the parent's directory -<c>ChangeLog</c> file. -</note> - -<section> -<title>Writing correct ChangeLog messages</title> -<body> -<note> -It is <b>very</b> important that your <c>cvs commit</c> messages are -also informative to aid the QA team or architecture teams as well as -other developers if they are trying to troubleshoot issues which are -known to not have occured in previous versions of ebuilds, for -example. If your ChangeLog message is concise there is usually nothing -wrong with using it as the <c>cvs commit</c> message. -</note> - -<p> -Your message should explain what specifically you changed and, if -relevant, why. You don't need to write an essay or even a complete -sentence (<c>ChangeLog</c> messages, however, are required to be in -'proper' English so no <c>fixed that bug kthx Bob</c> messages — -please do use punctuation), so long as it is easily understandable and -(preferably) greppable. Bad and good examples, all of which are based -upon real messages: -</p> - -<ul> - <li><b>BAD:</b> Changed keywords</li> - <li><e>GOOD:</e> Added ~x86 keyword</li> -</ul> - -<ul> - <li><b>BAD:</b> Stable</li> - <li><e>GOOD:</e> Stable on x86, sparc, mips</li> -</ul> - -<ul> - <li><b>BAD:</b> Fix stuff</li> - <li><e>GOOD:</e> Fix USE=foo logic error</li> -</ul> - -<ul> - <li><b>BAD:</b> .</li> - <li><e>GOOD:</e> Purge old ebuilds</li> -</ul> - -<ul> - <li> - <b>BAD:</b> Who the fuck reads this anyway? (<b>Editor's note</b>: - No, seriously, this is a genuine example. Do <e>not</e> do - this...) - </li> - <li><e>GOOD:</e> Version bump to 0.5.1.</li> -</ul> - -</body> -</section> -</body> -</chapter> -</guide> diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml index 4b8d042..fb0dab1 100644 --- a/ebuild-writing/misc-files/metadata/text.xml +++ b/ebuild-writing/misc-files/metadata/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/misc-files/metadata/"> <chapter> <title>Package and Category <c>metadata.xml</c></title> @@ -8,22 +8,38 @@ The <c>metadata.xml</c> file is used to specify additional data about a package or category. </p> +</body> <section> -<title>Package Metadata</title> +<title>Syntax</title> <body> + <p> -For packages, <c>metadata.xml</c> can specify a long description and -maintainer information. If a long description in any language is -provided, an English long description must be present. A typical -example might look like: +A metadata file follows the syntax defined in +<uri link="https://www.gentoo.org/glep/glep-0068.html">GLEP 68</uri>. +The character set <b>must</b> be UTF-8 as specified by +<uri link="https://www.gentoo.org/glep/glep-0031.html">GLEP 31</uri>. </p> -<subsection> -<body> +<p> +Concerning indentation there is no strict rule governing the style and +width. However the following minimal set of rules need to be followed: +</p> + +<ul> + <li> + Indentation should be consistent, i.e. either spaces or tabs, but + not both. + </li> + <li> + Keep the existing style when touching metadata.xml files that + belong to other developers. + </li> +</ul> <p> -A <path>metadata.xml</path> file can contain a number of tags: +The following table summarizes the tags that may appear in a +metadata.xml: </p> <table> @@ -33,182 +49,212 @@ A <path>metadata.xml</path> file can contain a number of tags: </tr> <tr> <ti> - <brite><pkgmetadata></brite> + <c><catmetadata></c> + </ti> + <ti> + This is the root element of the <c>metadata.xml</c> file for + categories. It has no attributes. It contains a number of + <c><longdescription></c> tags, each for a different language. + </ti> +</tr> +<tr> + <ti> + <c><pkgmetadata></c> </ti> <ti> - This is the root element of the <path>metadata.xml</path> file for + This is the root element of the <c>metadata.xml</c> file for packages. It has no attributes. The following subtags are allowed: - <brite><herd></brite>, - <brite><maintainer></brite>, - <brite><longdescription></brite>, - <brite><use></brite>, and - <brite><upstream></brite>. - There should be at least one <brite><herd></brite> or - <brite><maintainer></brite> subtag. + <c><maintainer></c>, + <c><longdescription></c>, + <c><stabilize-allarches></c>, + <c><slots></c>, + <c><use></c>, and + <c><upstream></c>. + While all the subtags are optional, <upstream> may + appear at most once. </ti> </tr> <tr> <ti> - <brite><catmetadata></brite> + <c><maintainer></c> </ti> <ti> - This is the root element of the <path>metadata.xml</path> file for - categories as per <uri link="https://wiki.gentoo.org/wiki/GLEP:34">GLEP 34</uri>. - It has no attributes. It contains a number of - <brite><longdescription></brite> tags, each for a different - language. + This tag specifies the persons and/or projects responsible for + the maintenance of a package. The <c>type</c> attribute must + be specified and can be either <c>"person"</c> or <c>"project"</c>. + There is one required subtag: + <c><email></c>. It has two optional subtags: + <c><name></c> and + <c><description></c>. </ti> </tr> <tr> + <ti><c><email></c></ti> <ti> - <brite><herd></brite> + This contains the e-mail address of the maintainer. It is required. </ti> +</tr> +<tr> + <ti><c><name></c></ti> <ti> - If a package is maintained by one or more herds, names of these herds - can be specified with the <brite><herd></brite> tag. The names - used in this tag must be the same as specified in the <uri - link="http://sources.gentoo.org/viewcvs.py/*checkout*/gentoo/xml/htdocs/proj/en/metastructure/herds/herds.xml?content-type=text/plain&rev=HEAD">herds.xml</uri> - file. + This contains freetext with the name of the maintainer. It is optional. </ti> </tr> <tr> + <ti><c><description></c></ti> <ti> - <brite><maintainer></brite> + The description tag contains a description of the maintainership, or for + example a remark that someone interested can take over the maintainership. + It is optional. </ti> +</tr> +<tr> + <ti><c><longdescription></c></ti> <ti> - Besides being part of a herd, a package can also be maintained directly. - The maintainers of a package can be specified with the - <brite><maintainer></brite> tag. This tag has one required subtag: - <brite><email></brite>. It has two optional subtags: - <brite><name></brite>, and <brite><description></brite>. + This tag contains a description for a category or a package. + For packages, it is used to augment the + <uri link="::ebuild-writing/variables/#Ebuild-defined Variables"> + DESCRIPTION</uri> field in the ebuilds themselves. This tag has + two optional subtags: <c><pkg></c> and <c><cat></c>. </ti> </tr> <tr> - <ti><brite><email></brite></ti> + <ti><c><stabilize-allarches></c></ti> <ti> - This contains the e-mail address of the maintainer. It is required. + Indicates an architecture-independent package. An ebuild can be marked + stable for all relevant architectures, when it has been tested on only one + architecture. This tag must have empty content. </ti> </tr> <tr> - <ti><brite><name></brite></ti> + <ti><c><slots></c></ti> <ti> - This contains freetext with the name of the maintainer. It is optional. + This tag describes the + <uri link="::general-concepts/slotting/">slots</uri> of a package. + It has two optional subtags: + <c><slot></c> and <c><subslots></c>. </ti> </tr> <tr> - <ti><brite><description></brite></ti> + <ti><c><slot></c></ti> <ti> - The description tag contains a description of the maintainership, or for - example a remark that someone interested can take over the maintainership. - It is optional. + This contains information for a particular slot. The <c>name</c> + attribute is mandatory and specifies the name of the slot. </ti> </tr> <tr> - <ti><brite><longdescription></brite></ti> + <ti><c><subslots></c></ti> <ti> - This tag contains a description of the package. This is to augment the - DESCRIPTION field in the ebuilds themselves. This tag has two optional - subtags: <brite><pkg></brite> and <brite><cat></brite>. + Describes the meaning of subslots for the whole package. This + tag may appear at most once. </ti> </tr> <tr> - <ti><brite><use></brite></ti> + <ti><c><use></c></ti> <ti> - This tag contains descriptions of <uri - link="::ebuild-writing/variables#iuse">USE flags</uri>. + This tag contains descriptions of + <uri link="::ebuild-writing/variables/#IUSE">USE flags</uri>. This tag is optional and, if specified, has one required subtag: - <brite><flag></brite>. + <c><flag></c>. </ti> </tr> <tr> - <ti><brite><flag></brite></ti> + <ti><c><flag></c></ti> <ti> This tag contains a description of how the named USE flag affects this - package. It is required if the <brite><use></brite> tag is specified. + package. It is required if the <c><use></c> tag is specified. It also requires the USE flag to be named in the <c>name</c> attribute. - This tag has two optional subtags: <brite><pkg></brite> and - <brite><cat></brite>. + This tag has two optional subtags: <c><pkg></c> and + <c><cat></c>. </ti> </tr> <tr> - <ti><brite><upstream></brite></ti> + <ti><c><upstream></c></ti> <ti> This tag contains information about the upstream developers/project. + It supports multiple optional subtags: <c><maintainer></c>, + <c><changelog></c>, <c><doc></c>, + <c><bugs-to>,</c>, and <c><remote-id></c>. </ti> </tr> <tr> - <ti><brite><maintainer></brite></ti> + <ti><c><maintainer></c></ti> <ti> - Name and e-mail of an upstream maintainer. May appear more than once. + Provides information about the upstream maintainer. It requires a + <c><name></c> subtag to be specified, supports an optional + <c><email></c> subtag and an optional <c>status</c> attribute. + Note that the <c>type</c> attribute <e>must not</e> be specified + for upstream maintainers. </ti> </tr> <tr> - <ti><brite><email></brite></ti> + <ti><c><name></c></ti> <ti> - The email address of an upstream may appear only once and must appear in first place. + The name of an upstream maintainer should contain a block of text with upstream's name. + This element is mandatory for an upstream maintainer and must appear exactly once. </ti> </tr> <tr> - <ti><brite><name></brite></ti> + <ti><c><email></c></ti> <ti> - The name of an upstream maintainer should contain a block of text with upstream's name. - This element is mandatory for an upstream maintainer and must appear only once. + The email address of an upstream maintainer. May appear only once. </ti> </tr> <tr> - <ti><brite><changelog></brite></ti> + <ti><c><changelog></c></ti> <ti> Should contain a URL where the location of the upstream changelog can be found. The URL must be version independent and must point to a changelog which is only updated on new releases of the corresponding package. (This also implies that one can link to an automatically updated changelog in case of vcs snapshots - only.) + only). May appear at most once. </ti> </tr> <tr> - <ti><brite><doc></brite></ti> + <ti><c><doc></c></ti> <ti> Should contain a URL where the location of the upstream documentation can be found. The link must not point to any third party documentation and must be version independent. If the documentation is available in more than one language, a lang attribute can be used which follows the same rules as the one for - longdescription. + <c><longdescription></c>. </ti> </tr> <tr> - <ti><brite><bugs-to></brite></ti> + <ti><c><bugs-to></c></ti> <ti> Should contain a place where bugs can be filed, a URL or an e-mail address prefixed - with mailto:. + with <c>mailto:</c>. May appear at most once. </ti> </tr> <tr> - <ti><brite><remote-id></brite></ti> + <ti><c><remote-id></c></ti> <ti> Should specify a type of package identification tracker and the identification that corresponds to the package in question. remote-id should make it easier to index information such as its Freshmeat ID or its CPAN name. + It has a mandatory attribute <c>type</c> which identifies the type + of upstream source. </ti> </tr> <tr> - <ti><brite><pkg></brite></ti> + <ti><c><pkg></c></ti> <ti> - This tag contains a valid package name in the format of a DEPEND. + This tag contains a valid qualified package name. </ti> </tr> <tr> - <ti><brite><cat></brite></ti> + <ti><c><cat></c></ti> <ti> This tag contains a valid category name as defined in - <path>profiles/categories</path>. + <c>profiles/categories</c>. </ti> </tr> </table> <p> -There are also some attributes that can be used with these tags. They are all -optional: +There are also some attributes that can be used with these tags: </p> <table> @@ -220,274 +266,416 @@ optional: <tr> <ti>lang</ti> <ti> - <brite><description></brite>, <brite><longdescription></brite>, - <brite><use></brite>, <brite><doc></brite> + <c><description></c>, <c><longdescription></c>, + <c><slots></c>, <c><use></c>, <c><doc></c> </ti> <ti> In every case where a description is required, there must be at <e>least</e> an english description. If an additional description in another language is given, this attribute is used to specify the language - used. The format is the two-character language code as defined by the <uri - link="http://www.w3.org/WAI/ER/IG/ert/iso639.htm#2letter">ISO-639-1</uri> - norm. + used. The format is an IETF language tag as defined by the + <uri link="https://tools.ietf.org/rfc/bcp/bcp47.txt">BCP 47</uri> + specification. Most often, this will be a two-character language code. </ti> </tr> <tr> <ti>restrict</ti> <ti> - <brite><herd></brite>, <brite><maintainer></brite>, - <brite><longdescription></brite>, <brite><flag></brite> + <c><maintainer></c>, <c><longdescription></c>, + <c><stabilize-allarches></c>, <c><flag></c> </ti> <ti> The restrict attribute allows one to restrict the application of certain - tags to certain versions of a package. When this attribute is used, a tag - without this attribute must also exist. That tag without the restrict - attribute will serve as the default. The format of the restrict attribute - is that of the DEPEND flag, except that "<" and - ">" need to be specified by &lt; and &gt;.<br /> - <br /> - For example, in the <c>sys-libs/db</c> package, - <c>restrict="&gt;=sys-libs/db-3.2.9-r5"</c> on the - <brite>maintainer</brite> tag shows that I'm currently maintaining all - versions greater then 3.2.9-r5. + tags to certain versions of a package. The format of the restrict attribute + is that of a EAPI 0 package dependency specification (i.e. USE-conditional + or slot dependendencies are not allowed). Since <c><</c> and <c>></c> + are special characters in XML, they must be escaped using <c>&lt;</c> + and <c>&gt;</c>. </ti> </tr> <tr> <ti>name</ti> <ti> - <brite><flag></brite> + <c><flag></c>, <c><slot></c> </ti> <ti> - This attribute is required on the <brite><flag></brite> tag. It - simply contains the USE flag. - <br /><br /> - For example, in the <c>sys-apps/hal</c> package, <c><flag name='acpi'> - Enables ACPI</flag></c> + When this attribute is required on the <c><flag></c> tag, it + simply contains the name of the USE flag. For the + <c><slot></c> tag, it specifies the + <uri link="::general-concepts/slotting/#Slot Names"> + slot name</uri> to which it applies. A slot name of <c>*</c> + allows for a single <c><slot></c> tag to match all the slots of a + package, in which case no other slot tags may be present. </ti> </tr> <tr> <ti>status</ti> <ti> - <brite><maintainer></brite> + <c><maintainer></c> </ti> <ti> - The upstream maintainer element has a status attribute, which is one of active or inactive. - This attribute is not mandatory. The absence of it shall be interpreted as unknown. - Please note: This attribute is only allowed in the <upstream> <maintainer> element! + The upstream maintainer element has a status attribute, which is + one of <c>"active"</c> or <c>"inactive"</c>. This attribute is not + mandatory. The absence of it shall be interpreted as + <c>"unknown"</c>. Please note that this attribute is only allowed + for the <c><maintainer></c> subtags of the <c><upstream></c> + element! </ti> </tr> <tr> <ti>type</ti> <ti> - <brite><remote-id></brite> + <c><remote-id></c> </ti> <ti> - A string identifying the type of upstream source. A list of valid strings are kept in metadata.dtd. + A string identifying the type of upstream source. A list of valid strings are kept in + <uri link="https://www.gentoo.org/dtd/metadata.dtd">metadata.dtd</uri>. Developers should email the gentoo-dev mailing list before using a new type value. </ti> </tr> +<tr> + <ti>type</ti> + <ti> + <c><maintainer></c> + </ti> + <ti> + Defines the type of the maintainer for a package. There are only + two valid values: <c>"person"</c> and <c>"project"</c>. The latter + denotes an official + <uri link="::general-concepts/projects/">Gentoo project</uri>. + </ti> +</tr> </table> </body> -</subsection> +</section> +<section> +<title>Package Metadata</title> +<body> +<p> +All packages <b>must</b> include a <c>metadata.xml</c> file which +provides information about package description, maintainers, local USE +flags, upstream etc. +</p> + +<p> +For developers' convenience, a skeleton file is provided in the +Gentoo tree with the name +<uri link="https://gitweb.gentoo.org/repo/gentoo.git/tree/skel.metadata.xml"> +skel.metadata.xml</uri>. The metadata file can also be created +using the <c>app-portage/metagen</c> tool. +</p> + +<p> +Commits of package metadata files are handled by <c>pkgdev</c> as +part of regular package maintenance. +</p> +<p> +Unless specified otherwise, the maintainer who is listed in the +metadata first shall be the assignee for the bugs for that package as +per <uri link="https://www.gentoo.org/glep/glep-0067.html#bug-assignment"> +GLEP 67</uri>. +</p> </body> -</section> -<section> -<title>Metadata Examples</title> <subsection> -<title>First Example</title> +<title>Package Metadata Examples</title> +<body> + +<p> +In the following sections, various examples of metadata.xml are +provided. These examples are based on actual package metadata files to +keep things as realistic as possible. However, they may not include +these files verbatim and should be taken as hypothetical examples. +</p> +</body> + +<subsubsection> +<title>Projects as Maintainers</title> <body> <p> -In this first example we provide you with the <path>metadata.xml</path> for -OpenOffice of which the ebuilds are completely managed by a herd called -<c>openoffice</c>: +For the first example, a package maintained by a single project is +presented. It is a simplified version of <c>metadata.xml</c> for +the package <c>app-office/libreoffice</c>. The package +maintainer is identified by the email address <c>office@gentoo.org</c> +with the name <c>Gentoo Office Project</c> as specified in the +optional <c><name></c> subtag. It also provides a long package +description. </p> <codesample lang="sgml"> -<?xml version='1.0' encoding='UTF-8'?> -<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> - <herd>openoffice</herd> + <maintainer type="project"> + <email>office@gentoo.org</email> + <name>Gentoo Office Project</name> + </maintainer> <longdescription> - OpenOffice is the opensource version of staroffice. - This ebuild allows you to compile it yourself. Unfortunately this - compilation can take up to a day depending on the speed of your - computer. It will however make a snappier openoffice than the binary - version. + LibreOffice is the successor of OpenOffice.org. This ebuild + allows you to compile it yourself. Unfortunately this compilation can + take up to a day depending on the speed of your computer. It will + however make a snappier LibreOffice than the binary version. </longdescription> </pkgmetadata> </codesample> <p> -The <c>openoffice</c> herd is defined in <path>herds.xml</path> by the -<uri link="http://www.gentoo.org/proj/en/metastructure">Gentoo Metastructure Project</uri>: +The email address <c>office@gentoo.org</c> corresponds to the +<c>Gentoo Office Project</c> as defined in +<uri link="https://api.gentoo.org/metastructure/projects.xml"> +projects.xml</uri>. This file lists all the projects in Gentoo and it +is generated from the +<uri link="https://wiki.gentoo.org/wiki/Project:Gentoo"> +projects listing</uri> available on the Gentoo Wiki: </p> -<note> -This example may be outdated when you read it. It's just an example! -</note> - <codesample lang="sgml"> -<herd> - <name>openoffice</name> - <email>openoffice@gentoo.org</email> - <description>Openoffice related packages</description> - <maintainer><email>pauldv@gentoo.org</email></maintainer> - <maintainer><email>suka@gentoo.org</email></maintainer> -</herd> +<project> + <email>office@gentoo.org</email> + <name>Gentoo Office Project</name> + <url>https://wiki.gentoo.org/wiki/Project:Office</url> + <description> + The Office project manages the office implementations + and related packages in Gentoo. + </description> + <member> + <email>dilfridge@gentoo.org</email> + <name>Andreas K. Hüttel</name> + <role>member</role> + </member> + <member> + <email>scarabeus@gentoo.org</email> + <name>Tomáš Chvátal</name> + <role>member</role> + </member> +</project> </codesample> -<p> -If you want to add (or remove) yourself from a herd, edit <path>herds.xml</path> -located in <path>[gentoo]/xml/htdocs/proj/en/metastructure/herds</path> in Gentoo's CVS repository. Make sure you -know the e-mail alias the herd listens to (for instance the "sound" herd has -<mail link="sound@gentoo.org">sound@gentoo.org</mail>) and add yourself to the -alias (by editing <path>/var/mail/alias/misc/<alias name></path> on -dev.gentoo.org). -</p> - </body> -</subsection> -<subsection> -<title>Second Example</title> +</subsubsection> +<subsubsection> +<title>Local USE Flag Descriptions</title> <body> <p> -For the second example, we will examine the <path>metadata.xml</path> of -<c>app-portage/mirrorselect</c>. This ebuild is maintained by the -<c>tools-portage</c> herd, but has a separate maintainer. +The second example is formed after the <c>metadata.xml</c> of +<c>sys-apps/portage</c>. It lists multiple maintainers where one +is a developer and the other is a project. It illustrates how local +USE flag descriptions are specified and also contains an upstream +element. It is also worth pointing out the use of <c>mailto:</c> +prefix in <c><bugs-to></c> tag due to the presence of an email address +as opposed to a URL. Conversely, email addresses specified in the +<c><email></c> tags require no such prefix. </p> <codesample lang="sgml"> -<?xml version='1.0' encoding='UTF-8'?> -<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> - <herd>tools-portage</herd> - <maintainer> - <email>johnm@gentoo.org</email> - <name>John Mylchreest</name> + <maintainer type="person"> + <email>larry@gentoo.org</email> + <name>Larry the Cow</name> </maintainer> - <longdescription> - This utility is used to select the fastest mirror (distfiles) and provide a - nicer front-end for mirror selection (both rsync + distfiles) to a user. - </longdescription> + <maintainer type="project"> + <email>dev-portage@gentoo.org</email> + </maintainer> + <use> + <flag name="epydoc">Build html API documentation with epydoc.</flag> + <flag name="ipc">Use inter-process communication between Portage and running ebuilds.</flag> + <flag name="pypy2_0">Use pypy-c2.0 as Python interpreter.</flag> + <flag name="python2">Use python2 as Python interpreter.</flag> + <flag name="python3">Use python3 as Python interpreter.</flag> + <flag name="xattr"> + Preserve extended attributes (filesystem-stored metadata) when + installing files. Usually only required for hardened systems. + </flag> + </use> + <upstream> + <bugs-to>mailto:dev-portage@gentoo.org</bugs-to> + <changelog>https://gitweb.gentoo.org/proj/portage.git/plain/RELEASE-NOTES</changelog> + <doc>https://wiki.gentoo.org/wiki/Handbook:AMD64/Working/Portage</doc> + </upstream> </pkgmetadata> </codesample> </body> -</subsection> -<subsection> -<title>Third Example</title> +</subsubsection> +<subsubsection> +<title>Split Maintainership</title> <body> <p> -For the third example, we will describe the <path>metadata.xml</path> of -<c>sys-apps/hal</c>. This ebuild is maintained by the <c>gentopia</c> herd -and contains USE flag descriptions. +This example splits the maintainership based on package versions using +the attribute <c>restrict</c>. According to the +<c>metadata.xml</c> of <c>sys-boot/grub</c>, the ebuilds +for version 2 and above are maintained by floppym@gentoo.org whereas +earlier versions are maintained by the Gentoo Base System +project. Note the use of "&gt;" as opposed to ">" in +<c>restrict</c>. +</p> + +<p> +The example also uses the <c><pkg></c> tag in USE flag +descriptions. Slot dependency specifiers are not allowed inside +<c><pkg></c>, therefore the notation +<c><pkg>sys-boot/grub</pkg>:2</c> is adopted as opposed to +<c><pkg>sys-boot/grub:2</pkg></c>. +</p> + +<p> +Lastly, the <c><remote-id></c> tag in the upstream description +is demonstrated. </p> <codesample lang="sgml"> -<?xml version="1.0" encoding="UTF-8"> -<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> -<herd>gentopia</herd> -<maintainer> - <email>compnerd@gentoo.org</email> -</maintainer> -<maintainer> - <email>steev@gentoo.org</email> -</maintainer> -<use> - <flag name='acpi'>Enables HAL to attempt to read from - /proc/acpi/event, if unavailable, HAL will read events from - <pkg>sys-power/acpid</pkg>. If you need multiple acpi - readers, ensure acpid is in your default runlevel along with HAL. This - will also enable HAL to read Toshia and IBM acpi events which do not - get sent via /proc/acpi/event</flag> - <flag name='crypt'>Allows HAL to mount volumes that are encrypted using - LUKS. <pkg>sys-fs/cryptsetup-luks</pkg> which has recently been renamed - to <pkg>sys-fs/cryptsetup</pkg> allows you to create such encrypted - volumes. HAL will be able to handle volumes that are removable or - fixed.</flag> - <flag name='dell'>Builds an installs the Dell addon, which reads data from - the Dell SM BIOS via <pkg>sys-libs/libsmbios</pkg>. It will read your - service tag information and your hardware backlight data as well as - allow you to modify the backlight settings on a Dell laptop.</flag> - <flag name='disk-partition'>Allows HAL to use libparted from - <pkg>sys-apps/parted</pkg> to read raw partition data from your disks - and process that data. Future versions of HAL (possibly 0.5.11 and - higher) will allow you to create, modify, delete and format partitions - from a GUI interface agnostic of your desktop environment.</flag> - <flag name='doc'>Generates documentation that describes HAL's fdi - format.</flag> - <flag name='pcmcia'>Allows HAL to process PCMCIA/CardBus slot data which - includes inserts and removals and act on these events.</flag> - <flag name='selinux'>Installs SELinux policies and links HAL to the SELinux - libraries.</flag> -</use> + <maintainer restrict="&gt;=sys-boot/grub-2" type="person"> + <email>floppym@gentoo.org</email> + </maintainer> + <maintainer type="project"> + <email>base-system@gentoo.org</email> + <name>Gentoo Base System</name> + </maintainer> + <use> + <flag name="device-mapper"> + Enable support for device-mapper from <pkg>sys-fs/lvm2</pkg> + </flag> + <flag name="efiemu"> + Build and install the efiemu runtimes + </flag> + <flag name="fonts">Build and install fonts for the gfxterm module</flag> + <flag name="mount"> + Build and install the grub-mount utility + </flag> + <flag name="libzfs"> + Enable support for <pkg>sys-fs/zfs</pkg> + </flag> + <flag name="multislot"> + Allow concurrent installation of <pkg>sys-boot/grub</pkg>:0 and + <pkg>sys-boot/grub</pkg>:2 by renaming all programs. + </flag> + <flag name="themes">Build and install GRUB themes (starfield)</flag> + <flag name="truetype"> + Build and install grub-mkfont conversion utility + </flag> + </use> + <upstream> + <remote-id type="sourceforge">dejavu</remote-id> + </upstream> </pkgmetadata> </codesample> </body> -</subsection> -<subsection> -<title>Fourth Example</title> +</subsubsection> +<subsubsection> +<title>Slots and Subslots</title> <body> <p> -This example demonstrates the usage of the upstream element: +The main focus of this example is to demonstrate how slots and +subslots are specified, by examining the metadata of +<c>media-libs/libpng</c>. There may be multiple reasons for +slotting depending on the nature of the package. For this particular +package, it can be seen that the slots are used to provide different +versions of the library with varying binary compatibility and that +developers are advised to build against the slot 0. Furthermore, +different versions of this package with the same subslot provide the +same Application Binary Interface (ABI), according to the description +specified in the <c><subslots></c> tag. </p> <codesample lang="sgml"> -<upstream> - <maintainer status="inactive"> - <email>foo@bar.bar</email> - <name>Foo Bar</name> - </maintainer> - <maintainer status="active"> - <email>foo@gentoo.org</email> - <name>Foo Gentoo</name> - </maintainer> - <changelog>http://foo.bar/changelog.txt</changelog> - <doc lang="en">http://foo.bar/doc/index.html</doc> - <doc lang="de">http://foo.bar/doc/index.de.html</doc> - <bugs-to>https://bugs.foo.bar</bugs-to> - <remote-id type="freshmeat">foobar</remote-id> - <remote-id type="sourceforge">foobar</remote-id> -</upstream> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> +<pkgmetadata> + <maintainer type="project"> + <email>base-system@gentoo.org</email> + <name>Gentoo Base System</name> + </maintainer> + <use> + <flag name="apng">support unofficial APNG (Animated PNG) spec</flag> + </use> + <upstream> + <remote-id type="cpe">cpe:/a:libpng:libpng</remote-id> + <remote-id type="sourceforge">apng</remote-id> + </upstream> + <slots> + <slot name="0"> + For building against. This is the only slot + that provides headers and command line tools. + </slot> + <slot name="1.2"> + For binary compatibility, provides libpng12.so.0 only. + </slot> + <slot name="1.5"> + For binary compatibility, provides libpng15.so.15 only. + </slot> + <subslots>Reflect ABI compatibility for libpng.so.</subslots> + </slots> +</pkgmetadata> </codesample> </body> +</subsubsection> </subsection> - +<subsection> +<title>Maintainer-Needed</title> +<body> <p> -All new packages <b>must</b> include a <c>metadata.xml</c> file. That file -should specify at least one herd or one maintainer. It is however recommended, -if at all possible, to find a herd willing to be listed. +Maintainer-needed ("orphaned") packages have no maintainers responsible for +them. Per +<uri link="https://www.gentoo.org/glep/glep-0067.html#case-of-maintainer-needed-packages"> +GLEP 67</uri>, these packages must not contain any <c><maintainer></c> +subtags under <c><pkgmetadata></c> in their <c>metadata.xml</c>. A strict +test for this condition would be: </p> -<p> -If a package has no maintainer, <c>maintainer-needed@gentoo.org</c> -should be listed as the maintainer. -</p> +<pre> +[[ $(xmllint --xpath "count(/pkgmetadata/maintainer)" metadata.xml) -eq 0 ]] +</pre> <p> -To easily create <c>metadata.xml </c>files, you can use -<c>app-portage/metagen</c>. There is also a skeleton file, see -<c>/usr/portage/skel.metadata.xml</c>. +By convention, a comment line containing the string <c>maintainer-needed</c> +is inserted. Other tags which are relevant to the package may be +present in the metadata. Bugs for these packages must be assigned to +<c>maintainer-needed@gentoo.org</c>. The QA team periodically generates the +<uri link="https://qa-reports.gentoo.org/output/maintainer-needed.html"> +orphaned packages list</uri> along with their corresponding bugs as +part of the QA reports. </p> -<p> -Commits of package metadata files are handled by <c>repoman</c>. You -should ensure that you have <c>dev-libs/libxml2</c> installed so that -the XML can be validated. -</p> +<codesample lang="sgml"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> +<pkgmetadata> + <!-- maintainer-needed --> + <upstream> + <maintainer status="active"> + <email>rasmus@alum.mit.edu</email> + <name>Matt Rasmussen</name> + </maintainer> + <doc lang="en">http://keepnote.org/manual/</doc> + <bugs-to>https://code.google.com/p/keepnote/issues/list</bugs-to> + </upstream> + <longdescription lang="en"> + KeepNote is a note taking application. With KeepNote, you can + store your class notes, TODO lists, research notes, journal entries, + paper outlines, etc in a simple notebook hierarchy with rich-text + formatting, images, and more. Using full-text search, you can + retrieve any note for later reference. + </longdescription> +</pkgmetadata> +</codesample> +</body> +</subsection> </section> <section> @@ -495,26 +683,22 @@ the XML can be validated. <body> <p> For categories, <c>metadata.xml</c> specifies a long description (in -English and optionally in other languages). The format is specified -formally in <uri link="https://wiki.gentoo.org/wiki/GLEP:34"> -GLEP 34</uri>, and the character set <b>must</b> be UTF-8 as specified -by <uri link="https://wiki.gentoo.org/wiki/GLEP:31">GLEP -31</uri>. A typical example: +English and optionally in other languages). A typical example: </p> <codesample lang="sgml"> - <?xml version="1.0" encoding="UTF-8"?> - <!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> - <catmetadata> - <longdescription lang="en"> - The app-vim category contains plugins and syntax file - packages for the Vim text editor. - </longdescription> - <longdescription lang="de"> - Die Kategorie app-vim enthält Plugins und Syntax-Pakete - für den Vim Texteditor. - </longdescription> - </catmetadata> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE catmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> +<catmetadata> + <longdescription lang="en"> + The app-vim category contains plugins and syntax file + packages for the Vim text editor. + </longdescription> + <longdescription lang="de"> + Die Kategorie app-vim enthält Plugins und Syntax-Pakete + für den Vim Texteditor. + </longdescription> +</catmetadata> </codesample> <p> @@ -531,13 +715,24 @@ is currently: <pre> xmllint --noout --valid metadata.xml -glep31check metadata.xml -cvs commit -m "Adding category metadata.xml for my-category" metadata.xml +git add metadata.xml +git commit --gpg-sign </pre> -</body> -</section> +<p> +The commit message should be formatted properly. +A sample commit is shown below: +</p> + +<pre> +commit db359439bcd52f5a7f20d2332ab62feb16657504 +Author: Alexis Ballier <aballier@gentoo.org> +Date: Tue Sep 22 10:47:49 2015 +0200 + + dev-ros: Add metadata.xml for the category. +</pre> </body> +</section> </chapter> </guide> diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml index 0be488c..56ba94c 100644 --- a/ebuild-writing/misc-files/patches/text.xml +++ b/ebuild-writing/misc-files/patches/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/misc-files/patches/"> <chapter> <title>Patches</title> @@ -18,29 +18,40 @@ is conventional. Patches are best named <c>${P}-what-it-does.patch</c> (or description of what the patch is for. If the patch is to fix a specific bug, it is often useful to add in the bug number <d/> for example, <c>vim-7.0-cron-vars-79981.patch</c>. If the patch is pulled from -upstream's CVS / SVN repository, it can help to include the revision +upstream's VCS repository, it can help to include the revision number in the patch name as a suffix to the version part <d/> <c>fluxbox-0.9.12-3860-menu-backups.patch</c>. </p> <p> -Larger patches should be <uri link="::general-concepts/mirrors/#suitable-download-hosts">mirrored</uri>, -preferrable on the Gentoo Infrastructure. When mirroring patches, choosing a -name that will not cause conflicts is important — the <c>${P}</c> -prefix is highly recommended here. Mirrored patches are often -compressed with <c>bzip2</c>. Remember to list these patches in -<c>SRC_URI</c>. +Larger patches should be +<uri link="::general-concepts/mirrors/#Suitable Download Hosts"> +mirrored</uri>, preferably on the Gentoo Infrastructure. When +mirroring patches, choosing a name that will not cause conflicts is +important — the <c>${P}</c> prefix is highly recommended +here. Mirrored patches are often compressed with <c>xz</c> or +<c>bzip2</c>. Remember to list these patches in <c>SRC_URI</c>. Please +see <uri link="::ebuild-maintenance/new-ebuild/#The files Directory"/> +for more information. </p> <note> Patches included in <c>${FILESDIR}</c> should never be compressed. </note> +<warning> +Starting from EAPI=6, the patch strip level defaults to <c>-p1</c>. +Although it can be overridden with a <c>eapply -p<strip_level></c> +command, it is highly recommended to adapt the patch itself to work +with the <c>-p1</c> default. +</warning> + <p> If a package requires many patches, even if they are individually small, it is often best to create a patch tarball to avoid cluttering up the tree too much. </p> +</body> <section> <title>Patch Descriptions</title> @@ -57,8 +68,8 @@ later. Good things to include in comments are: What the patch actually does. Bug numbers are good here. </li> <li> - Where the patch came from. Is it an upstream CVS/SVN pull, - something from Bugzilla, something you wrote? + Where the patch came from. For example, is it from an upstream VCS, + something from Bugzilla, or something you wrote? </li> <li> Whether the patch has been sent upstream, if applicable. @@ -85,8 +96,8 @@ from the <c>vim</c> patch tarball: <pre> # Detect Gentoo apache files properly. Gentoo bug 83565. ---- runtime/filetype.vim.orig 2005-03-25 01:44:12.000000000 +0000 -+++ runtime/filetype.vim 2005-03-25 01:45:15.000000000 +0000 +--- a/runtime/filetype.vim ++++ b/runtime/filetype.vim @@ -93,6 +93,9 @@ " Gentoo apache config file locations (Gentoo bug #76713) au BufNewFile,BufRead /etc/apache2/conf/*/* setf apache @@ -102,27 +113,347 @@ from the <c>vim</c> patch tarball: </section> <section> -<title>Adding Patches to the tree</title> +<title>Conditional patching</title> <body> <p> -When adding a patch to the tree be sure to check that the patch doesn't have -CVS keywords in it that will be expanded (such as <c>$Id$</c>). If the patch -contains these, it will break manifests unless you add it to the tree -correctly. In the case that it does have the keywords, you should add it by -doing: +Patching is ideally only done to make the package in question build properly, +and should not be done to modify the runtime behaviour of the package. This is +what USE flags and features of the package are for. As such, it is preferable to +apply patches unconditionally and avoid conditional patching. +</p> + +<p> +There are a number of reasons to avoid conditional patching: +</p> + +<ul> + <li> + It may go unnoticed that a patch fails to apply, if a package is not being + tested with a given flag + </li> + <li> + More variance is introduced and problems with a package can become much more + difficult to debug + </li> + <li> + Patches should preferably be upstreamed, but conditional patches cannot + </li> +</ul> + +<p> +Consider the following example <c>src_prepare()</c> implementation: +</p> + +<codesample lang="ebuild"> +src_prepare() { + if use threads; then + PATCHES+=( "${FILESDIR}"/${P}-mt.patch ) + fi + default +} +</codesample> + +<p> +As this patch is only applied when <c>USE="threads"</c> is set, any developer +creating new versions of this package might not detect whether the patch applies +successfully if they don't test with the same flag. +</p> + +<p> +Although conditional patching is discouraged it can be unavoidable and as such, +it is not considered a banned practice, but, to the extent possible, patches +should be written such that they affect behaviour correctly based on e.g. build +time definitions and configuration options rather than USE flags directly. This +allows them to be applied unconditionally. +</p> + +</body> +</section> + +<section> +<title>Clean Patch Howto</title> +<body> + +<p> +"Clean patch" does not refer to the patch itself (as in the changes it makes to +the source code). It refers to all the metadata that exists in the patch to +make it "maintainable". +</p> + +</body> + +<subsection> +<title>Why</title> +<body> + +<p> +This may take more effort "up front", but the amount of effort that it saves +for everyone else in the future more than makes up for it. This refers to other +distributions or upstream maintainers who read the patch, or future Gentoo +maintainers. By keeping all patches "clean", people can quickly and easily +assess a patch without searching through many other files. +</p> + +</body> +</subsection> + +<subsection> +<title>File Naming</title> +<body> + +<p> +Your patch name should be short and to the point. When doing a file listing +(e.g., <c>ls files/</c>), it's a lot easier to be able to scan for relevant +patches when they have good keywords in their file names. +</p> + +<p> +It should also include the package name and the version it was written against. +This way, people searching for patches or who happen to just stumble across the +file itself have a clue as to what it's for. Stripping out the <c>${PN}</c> +(and to a lesser extent, the <c>${PV}</c>) makes the filename significantly +less useful. The fact the files are typically stored in +<c>${CATEGORY}/${PN}/files/</c> is irrelevant, because the patch may be used +outside Gentoo. +</p> + +</body> +</subsection> + +<subsection> +<title>How</title> +<body> + +<p> +Here's a check list of things to keep in the patch header: +</p> + +<ul> + <li> + External references + <ul> + <li>Upstream mailing archives</li> + <li>Upstream bug reports</li> + <li>Upstream commit links</li> + <li>Upstream ChangeLog entries</li> + <li>Gentoo bug reports</li> + </ul> + </li> + <li> + Short/medium explanation + <ul> + <li>Why is the patch needed?</li> + <li>What is it fixing?</li> + <li>Why is it fixing it the way it is?</li> + <li>Proposal for better fixes in the future?</li> + <li>Is it a stop gap measure (workaround)?</li> + <li>How was it regression tested?</li> + <li> + Examples of before/after behaviour + <ul> + <li>How to reproduce bug without patch</li> + <li>How to show bug is fixed after patch</li> + <li> + Maybe upstream fixed it in a different way, so this test can be + used to show that the patch is no longer needed with newer versions + </li> + </ul> + </li> + </ul> + </li> + <li> + Status + <ul> + <li>Was it merged/rejected/postponed/etc. upstream?</li> + <li>Is it distribution-specific?</li> + </ul> + </li> + <li> + Attribution + <ul> + <li>Who found the bug?</li> + <li>Who fixed the bug?</li> + <li>Who wrote the patch?</li> + <li>Who tested the patch?</li> + <li>Who gave advice on the patch?</li> + </ul> + </li> +</ul> + +<p> +All this information should be <e>in the patch itself</e>. It should never be +found in something like the ebuild. If you really want to put a comment next +to a patch in an ebuild, then this is about the only thing that is OK +(where 93671 is the Gentoo bug number): +</p> + +<codesample lang="ebuild"> +PATCHES=( + "${FILESDIR}"/${P}-dont-umask.patch #93671 +) +</codesample> + +<p> +When documenting these things, it might be useful to use RFC822/Git-style tags +to format the metadata. So when documenting the author, use: +</p> + +<pre> +From: Nice Person <foo@cow.example.com> +</pre> + +<p> +Or when documenting relevant URLs, use something like: +</p> + +<pre> +Bug: https://upstream.example.com/12345 +Bug: https://bugs.gentoo.org/9889 +</pre> + +<p> +And if you want to note your copyright signoff, slap on a Signed-off-by tag: </p> <pre> -cvs add -ko files/${P}-the-cool-patch.patch +Signed-off-by: Diligent Developer <larry@gentoo.org> </pre> <p> -<c>-ko</c> disables keyword expansion for that specific file. If it doesn't -have keywords in it, then you can add it normally without the extra argument. +Finally, your patch should be clear of useless cruft. If it was not taken +straight from an upstream SCM (<c>git format-patch</c> or <c>svn diff -r #</c> +or <c>cvs diff -r 1.123 -r 1.124</c>), then the metadata is useless. So delete +it. This refers to things like the diff command used to produce the patch, +or the timestamps on the files, local revision info, or other similar spam. +Note that the context info (the stuff that comes after the <c>@@</c>) should +be left, as that can be invaluable when applying patches to later versions. +For example: </p> + +<pre> +@@ -80,6 +82,7 @@ case $sys in + ^^^^^^^^^^^^ keep this part +</pre> + +<p> +Extra points if you make the filename in the <c>---</c>/<c>+++</c> section +consistent and sane. That is, remove different leading <c>backup/paths/</c> +and <c>.orig</c>/<c>.new</c> suffixes. Your patch should be in the <c>-p1</c> +format because this tends to be much more standard than any other <c>-p#</c>. +It is also what <c>eapply</c> understands by default. A good suggestion is to +use either <c>a/</c> and <c>b/</c> (as in <c>git format-patch</c>) or the +package name/version as the leading portion that gets stripped. +</p> + +<p> +Also note that <c>patch</c> uses the timestamp info in order to remove empty +files automatically. Alternatively, you can specify the <c>-E</c> option with +<c>eapply</c> if you want to remove an empty file. +</p> + +<p> +Removed lines should not appear in the patch because they are commented <d/> +just remove them entirely. Patches show removed lines by prefixing them with +a <c>-</c>, so no information is lost by simply deleting lines rather than +commenting them out (which adds noise). This makes the patch shorter and +more readable. +</p> + +<p> +The following function (for your interactive shell, not for the ebuild) will +help deleting these things: +</p> + +<codesample lang="ebuild"> +scrub_patch() { + sed -i \ + -e '/^index /d' \ + -e '/^new file mode /d' \ + -e '/^Index:/d' \ + -e '/^=========/d' \ + -e '/^RCS file:/d' \ + -e '/^retrieving/d' \ + -e '/^diff/d' \ + -e '/^Files .* differ$/d' \ + -e '/^Only in /d' \ + -e '/^Common subdirectories/d' \ + -e '/^deleted file mode [0-9]*$/d' \ + -e '/^+++/s:\t.*::' \ + -e '/^---/s:\t.*::' \ + "$@" +} + +scrub_patch some-patch-you-found.patch +</codesample> + </body> -</section> +</subsection> + +<subsection> +<title>Examples</title> +<body> + +<p> +This shows a simple explanation and a URL for more info (this patch could do +with some attribution however). No metadata exists from running the <c>diff</c> +command (timestamps, etc.). +</p> + +<pre><!-- man-1.6d-fbsd.patch --> +Fixes compilation in FreeBSD. +https://bugs.gentoo.org/138123 + +--- man-1.6d/gencat/genlib.c ++++ man-1.6d/gencat/genlib.c +@@ -54,7 +54,7 @@ + #include <unistd.h> + #endif + +-#ifndef __linux__ ++#if !defined(__linux__) && !defined(__FreeBSD__) + #include <memory.h> + static int bcopy(src, dst, length) + char *src, *dst; +</pre> + +<pre><!-- util-linux-2.12q-dont-umask.patch --> +Don't force umask to 022 or the -o umask option doesn't work. +Patch by Daniel Drake. +https://bugs.gentoo.org/93671 + +--- mount/mount.c ++++ mount/mount.c +@@ -1491,8 +1491,6 @@ main(int argc, char *argv[]) { + if ((p = strrchr(progname, '/')) != NULL) + progname = p+1; + +- umask(022); +- + /* People report that a mount called from init without console + writes error messages to /etc/mtab + Let us try to avoid getting fd's 0,1,2 */ +</pre> + +<pre><!-- iproute2-2.6.25.20080417-build.patch --> +Don't let target flags bleed into build flags. +Fix by Bertrand Jacquin. +https://bugs.gentoo.org/226035 + +--- netem/Makefile ++++ netem/Makefile +@@ -2,6 +2,7 @@ DISTGEN = maketable normal pareto paretonormal + DISTDATA = normal.dist pareto.dist paretonormal.dist experimental.dist + + HOSTCC ?= $(CC) ++CCOPTS = $(CBUILD_CFLAGS) + LDLIBS += -lm + + all: $(DISTGEN) $(DISTDATA) +</pre> + </body> +</subsection> +</section> </chapter> </guide> diff --git a/ebuild-writing/misc-files/text.xml b/ebuild-writing/misc-files/text.xml index 31f1421..3ea435c 100644 --- a/ebuild-writing/misc-files/text.xml +++ b/ebuild-writing/misc-files/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/misc-files/"> <chapter> <title>Miscellaneous Files</title> @@ -18,6 +18,5 @@ This section contains some notes on various miscellaneous files. </chapter> <include href="metadata/"/> -<include href="changelog/"/> <include href="patches/"/> </guide> diff --git a/ebuild-writing/text.xml b/ebuild-writing/text.xml index 1107a9b..0be139b 100644 --- a/ebuild-writing/text.xml +++ b/ebuild-writing/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/"> <chapter> <title>Ebuild Writing</title> @@ -29,6 +29,6 @@ with some general notes and extended examples. <include href="using-eclasses/"/> <include href="functions/"/> <include href="misc-files/"/> +<include href="user-submitted/"/> <include href="common-mistakes/"/> -<include href="ebuild-maintenance/" /> </guide> diff --git a/ebuild-writing/use-conditional-code/text.xml b/ebuild-writing/use-conditional-code/text.xml index 3db3a40..655bbaa 100644 --- a/ebuild-writing/use-conditional-code/text.xml +++ b/ebuild-writing/use-conditional-code/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/use-conditional-code/"> <chapter> <title>USE Flag Conditional Code</title> @@ -15,7 +15,7 @@ readable. <p> The <c>if [ "`use foo`" ]</c> and <c>if [ -n "`use foo`" ]</c> forms which are -occasionally seen in older code must <b>not</b> be used. +occasionally seen in older code must <b>not</b> be used. This is because, since Portage 2.1, the 'use' Portage helper does not produce any output when the use flag is enabled or disabled so the [ "`use foo`" ] statement is pretty much identical to [ "" ] which always evaluates to false. </p> <note> @@ -25,25 +25,25 @@ statement. See <uri link="::ebuild-writing/error-handling/#die and Subshells"/>. </note> <codesample lang="ebuild"> - # USE conditional blocks... - if use livecd ; then - # remove some extra files for a small livecd install - rm -fr "${vimfiles}"/{compiler,doc,ftplugin,indent} - fi + # USE conditional blocks... + if use livecd ; then + # remove some extra files for a small livecd install + rm -fr "${vimfiles}"/{compiler,doc,ftplugin,indent} || die + fi - # Inverse USE conditional blocks... - if ! use cscope ; then - # the --disable-cscope configure arg doesn't quite work properly, - # so sed it out of feature.h if we're not USEing cscope. - sed -i -e '/# define FEAT_CSCOPE/d' src/feature.h || die "couldn't disable cscope" - fi + # Inverse USE conditional blocks... + if ! use cscope ; then + # the --disable-cscope configure arg doesn't quite work properly, + # so sed it out of feature.h if we're not USEing cscope. + sed -i -e '/# define FEAT_CSCOPE/d' src/feature.h || die "couldn't disable cscope" + fi - # USE conditional statements... - use ssl && epatch "${FILESDIR}/${P}-ssl.patch" - use sparc && filter-flags -fomit-frame-pointer + # USE conditional statements... + use ssl && eapply "${FILESDIR}/${P}-ssl.patch" + use sparc && filter-flags -fomit-frame-pointer - # Inverse USE conditional statements... - use ncurses || epatch "${FILESDIR}/${P}-no-ncurses.patch" + # Inverse USE conditional statements... + use ncurses || eapply "${FILESDIR}/${P}-no-ncurses.patch" </codesample> <p> diff --git a/ebuild-writing/user-submitted/text.xml b/ebuild-writing/user-submitted/text.xml new file mode 100644 index 0000000..58a372d --- /dev/null +++ b/ebuild-writing/user-submitted/text.xml @@ -0,0 +1,67 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-writing/user-submitted/"> +<chapter> +<title>User-submitted Ebuilds</title> + +<body> + +<p> +User-submitted ebuilds should never be blindly trusted and should +always be well-tested and audited before being committed to the tree. +The developer committing the user-submitted ebuild is vouching that +the ebuild meets all Gentoo Linux development standards. +</p> + +<p> +The user-submitted ebuild must not contain custom headers like this: +</p> + +<pre> +# Ebuild updated by: me <me@example.com> +</pre> + +<p> +Such information should be included in the git commit message instead. +The use of tags such as <c>Suggested-By:</c> or <c>Reported-By:</c> in +the commit message, as explained in the +<uri link="::ebuild-maintenance/git/#Git Commit Message Format"> +commit message format section</uri>, is highly encouraged. +Note that ebuilds received in the form of git patches or pull requests +will have the user as the commit author by default, in which case +including the user information in the commit message explicitly +may not be necessary. If that is not the case, you may wish to use +git commit's <c>--author</c> parameter to explicitly give them credit. +</p> + +<p> +Developers must check for a valid <c>Signed-off-by</c> line either within +the provided patches by a user or within a comment on e.g. Bugzilla. +See <uri link="::general-concepts/copyright-policy/#Certificate of Origin"/> +for details. +</p> + +<p> +Users should be encouraged to submit diffs to an existing ebuild if they +are submitting an upgrade. Doing this will help to avoid re-introduction +of previously fixed bugs into "new" ebuilds. When not working from a +diff but from a complete user-submitted ebuild, the <c>diff -u</c> command +should be used to see what has changed; attention should be payed for +anything from the current ebuild that should appear in the new ebuild, +or anything in the new ebuild that should be fixed or removed. +</p> + +<p> +In general, it is preferable to have the user do the work required to +get their ebuild up to par, so that they can learn from their mistakes +and submit cleaner ebuilds in the future. Be sure to be thankful for any +submission, even if it isn't very good. Be polite but honest <d/> if an +ebuild isn't usable, the user can be told in a way that does not insult +their current ebuild-writing abilities. Remember that the user who +submitted that broken ebuild may be a skilled and productive member of +our project in the future <d/> that is, if they receive the right amount +of encouragement and support and continue to improve in their abilities. +</p> + +</body> +</chapter> +</guide> diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml index 5030318..80f9b5b 100644 --- a/ebuild-writing/users-and-groups/text.xml +++ b/ebuild-writing/users-and-groups/text.xml @@ -1,89 +1,323 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/users-and-groups/"> <chapter> <title>Users and Groups</title> <body> <p> -If your ebuild requires a user or group to be added for a daemon, for example, -this should be performed via the functions available in <c>user.eclass</c>. -Regardless of whether you are adding a group or a user, this should be performed -in the <c>pkg_setup</c> function: <c>pkg_setup</c> is sandbox-safe, -is called before the compile process so a build that requires the user to exist will -have it, and is also called for both binary and source packages. You may also -use the <c>pkg_preinst</c> or <c>pkg_postinst</c> functions for user creation, if -the user is not required during or before <c>src_install</c>. +Creating users and groups is governed by <uri +link="https://gentoo.org/glep/glep-0081.html">GLEP 81</uri>. It is implemented +via <c>acct-user</c> and <c>acct-group</c> eclasses. New users and groups +are created as packages respectively in <c>acct-user</c> and <c>acct-group</c> +categories. +</p> + +<p> +First, check the <uri link="https://api.gentoo.org/uid-gid.txt">UID/GID +assignment list</uri> and choose a free UID/GID in the range between 101 and +749. If you are adding a user and a group with the same name, use the same +number for their UID and GID, respectively. When in doubt, take the next free +number from 101 upwards. The helper script <c>./bin/used_free_uidgids.sh</c> +available in the data/api.git repository can be used to find the next available +UID or GID. +</p> + +<p> +Add your new user(s) and group(s) to the <c>uid-gid.txt</c> file +located in the +<uri link="https://gitweb.gentoo.org/data/api.git">data/api.git</uri> +repository and push them before adding the actual packages. +This counts as reserving the identifiers and will prevent collisions. +Afterwards, you can push the new ebuilds. +</p> + +<p> +The historical way of using <c>user.eclass</c> directly is now deprecated +and must not be used for new packages. </p> </body> <section> -<title>Adding Groups</title> +<title>Group ebuilds</title> <body> <p> -To add a group, use the <c>enewgroup</c> function: +Group ebuilds are placed in <c>acct-group</c> category, with the package name +matching the group name. The following ebuild for <c>acct-group/suricata</c> +can be used as a template for writing group ebuilds: </p> <pre> -enewgroup <name> [gid] +# Copyright 2019-2021 Gentoo Authors +# Distributed under the terms of the GNU General Public License v2 + +EAPI=7 + +inherit acct-group + +DESCRIPTION="Group for Suricata IDS" +ACCT_GROUP_ID=477 </pre> <p> -By default the next available group ID is selected. To set a specfic group ID, -pass it an extra argument to <c>enewgroup</c>. +<c>ACCT_GROUP_ID</c> must be set to the requested GID. </p> -<note> -Group IDs should rarely be hardcoded. If this is the case, you should -probably check first on gentoo-dev. -</note> - </body> </section> <section> -<title>Adding Users</title> +<title>User ebuilds</title> <body> <p> -To add a user, use the <c>enewuser</c> function: +User ebuilds are placed in <c>acct-user</c> category, with the package name +matching the user name. The following ebuild for <c>acct-user/suricata</c> +can be used as a template for writing user ebuilds: </p> <pre> -enewuser <user> [uid] [shell] [homedir] [groups] [params] +# Copyright 2019-2021 Gentoo Authors +# Distributed under the terms of the GNU General Public License v2 + +EAPI=7 + +inherit acct-user + +DESCRIPTION="User for Suricata IDS" +ACCT_USER_ID=477 +ACCT_USER_GROUPS=( ${PN} ) + +acct-user_add_deps </pre> <p> -By default, both <c>enewuser</c> and <c>enewgroup</c> allocate the next available user -ID or group ID to the new user or group - if not, you explicitly have to specify -one. +<c>ACCT_USER_ID</c> must be set to the requested GID. <c>ACCT_USER_GROUPS</c> +should list all the groups user belongs to, the primary group first. All +the other keys are optional. +</p> + +<p> +<c>ACCT_USER_SHELL</c> can be used to set the shell for the user. If unset, +the best system equivalent of nologin is used. <c>ACCT_USER_HOME</c> specifies +the home directory, with <c>/dev/null</c> being the default. +<c>ACCT_USER_HOME_OWNER</c> can be used to override the ownership of the home +directory, and <c>ACCT_USER_HOME_PERMS</c> to override the default permissions. +The defaults are the user and primary group for the owner, and 0755 for the +permissions. +</p> + +<important> +Whenever possible, the default shell and home directory should be +used. The rationale for this is explained below. +</important> + +<p> +You should embark upon a GLEP81 migration like an EAPI +update. Rather than simply copy your user's settings into an +<c>acct-user</c> package, you should take the opportunity to +re-evaluate your user's name, shell, home directory, and its +permissions. Our GLEP 81 implementation will reveal many user +management issues that were allowed to fester in the past. +</p> +</body> + +<subsection> +<title>Choosing a shell</title> +<body> +<p> +In most cases, the default shell (that is, no shell) should be +used. Services can still be started as a user who has no shell, and +daemons are able to drop privileges to a user who has no shell. If +necessary, the administrator can override a user's default shell with +<c>su -s <shell> <username></c>. This is sufficient for +testing, management of SSH credentials, and for initial configuration +in an ebuild's <c>pkg_config</c> phase. +</p> +<p> +An obvious exception to this rule is if a human being will need to log +into the account interactively, as is the case with the <c>root</c> +user. Other exceptions certainly exist, but should be evaluated +case-by-case. In other words, if you haven't checked, don't set your +user's shell to <c>/bin/bash</c> because you think he <e>might</e> +need it. +</p> +<p> +The goal here is twofold. First, the principle of least privilege says +that if a user doesn't need a real shell, he shouldn't have one. And +along those same lines, not having a shell gives the system +administrator some peace of mind: he doesn't have to be as concerned +with whether or not that user has a password (and how strong it is), +or whether or not its filesystem permissions are all set correctly, or +whether or not it can log in via SSH, et cetera. +</p> +</body> +</subsection> + +<subsection> +<title>Choosing a home directory</title> +<body> +<p> +In most cases, the default home directory (that is, no home directory) +should be used. GLEP81 changed two aspects of user management with +respect to home directories: +</p> + +<ol> + <li> + Creating a user can now modify the permissions on an existing + directory. Should the need arise, this is necessary for a new + version of an <c>acct-user</c> package to be able to fix the + ownership and permissions of its home directory. + </li> + <li> + All user data aside from the username became non-local to ebuilds + that depend on that user. This is merely a side-effect of moving + the user creation out of the client package, and into a separate + <c>acct-user</c> package. + </li> +</ol> + +<p> +The first item means that you should be conservative when choosing a +home directory. If at all possible, avoid choosing a home directory +that is used by another package. In particular, no two +<c>acct-user</c> packages should use the same home directory. At best, +the ownership and permissions on a shared home directory would need to +be kept synchronized between all packages that share it. At worst, one +package goes out-of-sync and introduces a security hole for the others +who no longer have the expected permissions. +</p> +<p> +The second item means that if your package requires a user, you can +no longer be sure of that user's home directory or its ownership and +permissions. If your package requires a directory to be owned and +writable by some user, then your package's ebuild should create that +directory and ensure that it is writable by the user. In other +words, you should not rely on the directory being created +"transitively" by a dependency, even if that dependency is an +<c>acct-user</c> package. +</p> +<p> +In summary, +</p> +<ul> + <li> + Avoid using an <c>ACCT_USER_HOME</c> that belongs to another + package. + </li> + <li> + No two acct-user packages should define the same + <c>ACCT_USER_HOME</c>. + </li> + + <li> + If for example your package's configuration needs <username> + to be able to write to <c>/var/lib/<username></c>, then your + package's ebuild should create that directory and set its + ownership and permissions. Barring any other considerations, the + corresponding <c>acct-user</c> package should leave + <c>ACCT_USER_HOME</c> at its default (empty) value; setting + <c>ACCT_USER_HOME=/var/lib/<username></c> creates + unnecessary duplication and risks desynchronizing the permissions. + </li> +</ul> +</body> +</subsection> + +<subsection> +<title>Choosing home directory ownership</title> +<body> +<p> +In most cases, the default home directory ownership is correct. If a +non-default home directory is needed at all, then it should be +writable by its user and giving ownership of it to someone else would +prevent that. Being unwritable indicates that a shared and potentially +sensitive location was chosen. Moreover, the fact that the home +directory is not writable suggests that the default home directory +(which is also not writable) would suffice instead; the home directory +guidelines explain why the default is preferable in that case. For +example, setting <c>ACCT_USER_HOME_OWNER="root:root"</c> is suspicious +because it appears intended to "undo" the ownership changed by your +user package, and that would only be necessary if the path in question +is used by some other package. +</p> +</body> +</subsection> + +<subsection> +<title>Choosing home directory permissions</title> +<body> +<p> +In many cases, the default home directory permissions (0755) will +suffice. But, if your package will work with mode 0700 or 0750, then +those are preferable. This is the principle of least privilege +again. If your package works with a non-writable home directory, then +you should probably be using the default of <e>no</e> home directory! +</p> +<warning> +The world-writable bit should never be set in +<c>ACCT_USER_HOME_PERMS</c>. This should never be necessary, and is +usually exploitable. +</warning> +</body> +</subsection> + +<subsection> +<title>Epilogue</title> +<body> +<p> +These suggestions are not rules and are not written in stone, except +perhaps for the world-writable warning. There are packages in the tree +that <c>chroot()</c> to <c>$HOME</c>, and require that directory to be +owned by <c>root:root</c> for security reasons. In cases like that, +it's impossible to avoid implicitly tying the user to the package that +needs it via the home directory, and the best you can do is attempt to +ensure that the users and paths are unique so that no conflicts arise. +</p> + +<p> +Unless your package is exceptional, though, following these guidelines +will minimize the potential for problems down the road. </p> +</body> +</subsection> +</section> + +<section> +<title>Utilizing users and groups in packages</title> +<body> <p> -Arguments for <c>enewuser</c> must be passed in the order as shown above: if you do -not want to specify a fixed user ID however but do want to set a specific shell, -for example, use <c>-1</c> for the <c>uid</c> parameter. The same applies for any other -parameter where you want to keep the default setting. +In order to make your package install specific users and groups, specify them +as dependencies. Accounts needed at build time must be included +in <c>DEPEND</c>, and accounts needed at runtime must be included +in <c>RDEPEND</c>. </p> <p> -Groups for the <c>groups</c> argument should be separated by a comma (<c>,</c>) and -wrapped correctly, for example: +For example, an ebuild requiring the user and group <c>foo</c> at runtime would +specify: </p> <pre> -enewuser frozd -1 -1 -1 "backup,frozd" +RDEPEND=" + acct-user/foo + acct-group/foo" </pre> <p> -Finally, any data left over for the <c>params</c> argument is passed directly to -useradd. +This would also be sufficient if ownership of installed files were set +in <c>pkg_preinst</c>. However, if the ebuild needs the user and group +to be present at build-time already, it would specify: </p> -<note> -User IDs should rarely be hardcoded. If this is the case, you should -probably check first on gentoo-dev. -</note> +<pre> +RDEPEND=" + acct-user/foo + acct-group/foo" +DEPEND="${RDEPEND}" +</pre> </body> </section> diff --git a/ebuild-writing/using-eclasses/text.xml b/ebuild-writing/using-eclasses/text.xml index de9ec7f..db41d25 100644 --- a/ebuild-writing/using-eclasses/text.xml +++ b/ebuild-writing/using-eclasses/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/using-eclasses/"> <chapter> <title>Using Eclasses</title> @@ -7,7 +7,7 @@ <p> An eclass is a collection (library) of functions or functionality that is shared between packages. See <uri link="::eclass-writing/" /> for the full story on what -eclasses can do, how they work and how to write them, and <uri link="::eclass-reference/">the eclass reference</uri> +eclasses can do, how they work and how to write them, and <uri link="::eclass-reference/"/> for documentation on various commonly used eclasses. This section only explains how to use an eclass which has already been written. </p> @@ -19,55 +19,65 @@ how to use an eclass which has already been written. <p> To use an eclass, it must be 'inherited'. This is done via the <c>inherit</c> -function, which is provided by <c>ebuild.sh</c>. The <c>inherit</c> statement must -come at the top of the ebuild, <e>before</e> any functions. Conditional inherits are -illegal (except where the inheritance criteria are cache-constant <d/> see <uri -link="::general-concepts/portage-cache"/>). +function, which is provided by <c>ebuild.sh</c>. The <c>inherit</c> statement +must come at the top of the ebuild, <e>before</e> any functions. +Conditional inherits are illegal (except where the inheritance criteria are +cache-constant <d/> see <uri link="::general-concepts/portage-cache/"/>). </p> <p> -After inheriting an eclass, its provided functions can be used as normal. Here'san example ebuild, <c>foomatic-0.1-r2.ebuild</c>, which uses four eclasses: +When using <c>inherit</c>, it is best practice to sort the arguments (eclasses) +alphabetically. An exception is where the phases exported by an eclass are +affected by subsequent arguments. For example, <c>multilib-minimal.eclass</c> +mentions in its +<uri link="::eclass-reference/multilib-minimal.eclass/">documentation</uri> +that it should be inherited last because it overrides most phases. +</p> + +<p> +After inheriting an eclass, its provided functions can be used as +normal. Here's an example ebuild, <c>foomatic-0.1-r2.ebuild</c>, which +uses three eclasses: </p> <codesample lang="ebuild"> -# Copyright 1999-2010 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -EAPI="2" +EAPI=7 -inherit eutils bash-completion flag-o-matic autotools +inherit autotools bash-completion-r1 flag-o-matic DESCRIPTION="Tool for foo" -HOMEPAGE="http://foomatic.sf.net" +HOMEPAGE="https://foomatic.sf.net" SRC_URI="mirror://sourceforge/${PN}/${P}.tar.gz" LICENSE="GPL-2" SLOT="0" -KEYWORDS="alpha ~amd64 ~x86 ~x86-fbsd" +KEYWORDS="alpha ~amd64 ~x86 ~x64-macos" -RDEPEND=">=sys-libs/ncurses-5.2 - >=sys-libs/readline-4.1" +RDEPEND="sys-libs/ncurses:0= + >=sys-libs/readline:0=" DEPEND="${RDEPEND}" src_prepare() { - epatch "${FILESDIR}/${P}-gentoo.patch" + eapply "${FILESDIR}/${P}-gentoo.patch" + eapply_user eautoreconf } src_configure() { - econf --sysconfdir=/etc/devtodo + econf --sysconfdir="${EPREFIX}"/etc/devtodo } src_compile() { replace-flags -O? -O1 - emake || die "emake failed" + default } src_install() { - emake DESTDIR="${D}" install || die "emake install failed" - dodoc AUTHORS ChangeLog README TODO || die "dodoc failed" - dobashcompletion "${FILESDIR}/${PN}.bash-completion" ${PN} + default + dobashcomp "${FILESDIR}/${PN}.bash-completion" ${PN} } </codesample> @@ -77,11 +87,11 @@ Note the <c>inherit</c> immediately after the header. </p> <p> -The <c>eutils</c> eclass (see <uri link="::eclass-reference/eutils.eclass/">eutils.eclass</uri>) is needed to get the -<c>epatch</c> function. The <c>flag-o-matic</c> eclass (see <uri -link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic.eclass</uri>) is needed for <c>replace-flags</c>, and -the <c>bash-completion</c> eclass (<uri link="::eclass-reference/bash-completion.eclass/">bash-completion.eclass</uri>) is used -to handle the bash completion file via <c>dobashcompletion</c> and <c>bash-completion_pkg_postinst</c>. +The <c>autotools</c> eclass (see <uri link="::eclass-reference/autotools.eclass/"/>) is needed to get the +<c>eautoreconf</c> function. The <c>flag-o-matic</c> eclass (see <uri +link="::eclass-reference/flag-o-matic.eclass/"/>) is needed for <c>replace-flags</c>, and +the <c>bash-completion-r1</c> eclass (<uri link="::eclass-reference/bash-completion-r1.eclass/"/>) is used +to handle the bash completion file via <c>dobashcomp</c>. </p> </body> diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml index a31baa2..af03749 100644 --- a/ebuild-writing/variables/text.xml +++ b/ebuild-writing/variables/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/variables/"> <chapter> <title>Variables</title> @@ -16,8 +16,9 @@ which are of use throughout the ebuild. <body> <p> -The following variables are defined for you. You must not attempt to set -them. +The following variables are defined for you. You must not attempt to +set them. Developers must not rely on package manager specific values +for these variables when writing ebuilds. </p> <table> @@ -64,14 +65,14 @@ them. <ti><c>FILESDIR</c></ti> <ti> Path to the ebuild's <c>files/</c> directory, commonly used - for small patches and files. Value: + for small patches and files. For example: <c>"${PORTDIR}/${CATEGORY}/${PN}/files"</c>. </ti> </tr> <tr> <ti><c>WORKDIR</c></ti> <ti> - Path to the ebuild's root build directory. Value: + Path to the ebuild's root build directory. For example: <c>"${PORTAGE_BUILDDIR}/work"</c>. </ti> </tr> @@ -79,21 +80,30 @@ them. <ti><c>T</c></ti> <ti> Path to a temporary directory which may be used by the - ebuild. Value: <c>"${PORTAGE_BUILDDIR}/temp"</c>. + ebuild. For example: <c>"${PORTAGE_BUILDDIR}/temp"</c>. </ti> </tr> <tr> <ti><c>D</c></ti> <ti> - Path to the temporary install directory. Value: + Path to the temporary install directory. For example: <c>"${PORTAGE_BUILDDIR}/image"</c>. </ti> </tr> <tr> + <ti><c>HOME</c></ti> + <ti> + Path to a temporary directory for use by any programs invoked by + an ebuild that may read or modify the home directory. For example: + <c>"${PORTAGE_BUILDDIR}/homedir"</c>. + </ti> + </tr> + <tr> <ti><c>ROOT</c></ti> <ti> - Path to the root directory. When not using <c>${D}</c>, - always prepend <c>${ROOT}</c> to the path. + The absolute path to the root directory into which the package is to be + merged. Only allowed in pkg_* phases. + See <uri link="::ebuild-writing/variables/#ROOT"/> </ti> </tr> <tr> @@ -103,9 +113,129 @@ them. fetched for the package are stored. </ti> </tr> + <tr> + <ti><c>EPREFIX</c></ti> + <ti> + The normalised offset-prefix path of an offset installation. + See <uri link="https://wiki.gentoo.org/wiki/Project:Prefix/Technical_Documentation"> + Gentoo Prefix Technical Documentation</uri> for more information. + </ti> + </tr> + <tr> + <ti><c>ED</c></ti> + <ti> + Shorthand for <c>${D%/}${EPREFIX}/</c>. + </ti> + </tr> + <tr> + <ti><c>EROOT</c></ti> + <ti> + Shorthand for <c>${ROOT%/}${EPREFIX}/</c>. + </ti> + </tr> + <tr> + <ti><c>SYSROOT</c></ti> + <ti> + (EAPI=7) The absolute path to the root directory containing build dependencies + satisfied by <c>DEPEND</c> + </ti> + </tr> + <tr> + <ti><c>ESYSROOT</c></ti> + <ti> + (EAPI=7) Shorthand for <c>${SYSROOT%/}${EPREFIX}/</c>. + </ti> + </tr> + <tr> + <ti><c>BROOT</c></ti> + <ti> + (EAPI=7) The absolute path to the root directory containing build dependencies + satisfied by <c>BDEPEND</c>, typically executable build tools. + </ti> + </tr> + <tr> + <ti><c>MERGE_TYPE</c></ti> + <ti> + The type of package that is being merged. Possible values are: + <c>source</c> if building and installing a package from source, + <c>binary</c> if installing a binary package previously built from + the ebuild, <c>buildonly</c> if building a binary package without + installing it. + </ti> + </tr> + <tr> + <ti><c>REPLACING_VERSIONS</c></ti> + <ti> + A whitespace-separated list of all versions (<c>PVR</c>) of this package + that are being replaced (uninstalled or overwritten) as a result of this + install. It is a list, not a single optional value, to handle pathological + cases such as installing <c>foo-2:2</c> to replace <c>foo-2:1</c> and + <c>foo-3:2</c>. Available in <c>pkg_preinst</c> and <c>pkg_postinst</c>. + </ti> + </tr> + <tr> + <ti><c>REPLACED_BY_VERSION</c></ti> + <ti> + The single version (<c>PVR</c>) of this package that is replacing the + version provided by this ebuild, if it is being uninstalled as part of + an install. An empty string otherwise, i.e., if it is being uninstalled + without replacement. Available in <c>pkg_prerm</c> and <c>pkg_postrm</c>. + </ti> + </tr> </table> </body> + +<subsection> +<title>ROOT</title> +<body> + +<p> +The idea behind <c>ROOT</c> is that one can build a system with +<c>ROOT=/somewhere</c> and then chroot into it or tar up +<c>/somewhere</c> as a system image. It is not designed to allow the +user to run <c>/somewhere/usr/bin/foo</c>. +</p> + +<p> +Ebuilds may reference <c>ROOT</c> only during <c>pkg_*</c> phases. It +can't be used correctly in <c>src_*</c> phases, since <c>ROOT</c> may +be different when merging a binary package. For example, a binary +package may be built with <c>ROOT=/</c> and then installed onto a +system using <c>ROOT=/somewhere</c>. +</p> + +<p> +When building a package, <c>ROOT</c> should not be used to satisfy the +required dependencies on libraries, headers files etc. Instead, the +files on the build system should be specified using <c>/</c>. +</p> + +<p> +In a cross compiling environment, ebuilds must not call any of the +binaries inside <c>ROOT</c> since they may not be executable on the +build system. +</p> + +<p> +Below is an example of an ebuild that uses <c>ROOT</c> in +<c>pkg_postinst()</c> to conditionally print an error message if an +old and obsolete configuration file still exists: +</p> + +<codesample lang="ebuild"> +pkg_postinst() { + if [[ -e ${ROOT}/etc/oldconfig ]]; then + ewarn "You still have the obsolete config file" + ewarn " ${ROOT}/etc/oldconfig." + ewarn "Please migrate your settings to ${ROOT}/etc/newconfig" + ewarn "and remove ${ROOT}/etc/oldconfig." + fi +} +</codesample> + +</body> +</subsection> </section> <section> @@ -124,24 +254,27 @@ The following variables may or must be defined by every ebuild. <tr> <ti><c>EAPI</c></ti> <ti> - The EAPI. See <uri link="::ebuild-writing/eapi"/>. + The EAPI. See <uri link="::ebuild-writing/eapi/"/>. </ti> </tr> <tr> <ti><c>DESCRIPTION</c></ti> <ti> - A short (less than 80 characters) description of the package's + A short (not more than 80 characters) description of the package's purpose. Mandatory. </ti> </tr> <tr> <ti><c>HOMEPAGE</c></ti> <ti> - Package's homepage. Mandatory (except for virtuals). If you are - unable to locate an official one, try to provide a link to - <uri link="http://freshmeat.net">freshmeat.net</uri> or a similar - package tracking site. Never refer to a variable name in the - string; include only raw text. + Package's homepage(s). Mandatory (except for virtuals), accepts + multiple values. In some contexts, it is customary to provide + package tracker and/or code hosting links besides the main homepage + (e.g. PyPI link for Python packages, GitHub link when code can't + easily be found on homepage) for convenience. If no homepage for + the package is available, please set it to + <c>https://wiki.gentoo.org/wiki/No_homepage</c>. + Never refer to a variable name in the string; include only raw text. </ti> </tr> <tr> @@ -149,7 +282,7 @@ The following variables may or must be defined by every ebuild. <ti> A list of source URIs for the package. Can contain <c>USE</c>-conditional parts, see - <uri link="::ebuild-writing/variables#SRC_URI"/>. + <uri link="::ebuild-writing/variables/#SRC_URI"/>. </ti> </tr> <tr> @@ -157,20 +290,20 @@ The following variables may or must be defined by every ebuild. <ti> The package's license, corresponding exactly (including case) to a file in <c>licenses/</c>. Mandatory (except for virtuals). - See <uri link="::ebuild-writing/variables#LICENSE"/>. + See <uri link="::ebuild-writing/variables/#LICENSE"/>. </ti> </tr> <tr> <ti><c>SLOT</c></ti> <ti> The package's <c>SLOT</c>. Mandatory. - See <uri link="::ebuild-writing/variables#SLOT"/>. + See <uri link="::ebuild-writing/variables/#SLOT"/>. </ti> </tr> <tr> <ti><c>KEYWORDS</c></ti> <ti> - See <uri link="::ebuild-writing/variables#KEYWORDS"/> and + See <uri link="::ebuild-writing/variables/#KEYWORDS"/> and <uri link="::keywording/"/>. </ti> </tr> @@ -178,22 +311,29 @@ The following variables may or must be defined by every ebuild. <ti><c>IUSE</c></ti> <ti> A list of all <c>USE</c> flags (excluding arch flags, but - including <c>USE_EXPAND</c> flags) used within the ebuild. See - <uri link="::ebuild-writing/variables#IUSE"/>. + including <c>USE_EXPAND</c> flags) used within the ebuild. + See <uri link="::ebuild-writing/variables/#IUSE"/>. </ti> </tr> <tr> <ti><c>REQUIRED_USE</c></ti> <ti> - A list of assertions that must be met by the configuration of - <c>USE</c> flags to be valid for this ebuild. (Requires - <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri>.) + A list of assertions that must be met by the configuration of <c>USE</c> + flags to be valid for this ebuild. + See <uri link="::ebuild-writing/variables/#REQUIRED_USE"/>. + </ti> + </tr> + <tr> + <ti><c>PROPERTIES</c></ti> + <ti> + A space-delimited list of properties, with conditional syntax support. + <c>interactive</c>, <c>live</c>, and <c>test_network</c> are valid values. </ti> </tr> <tr> <ti><c>RESTRICT</c></ti> <ti> - A space-delimited list of portage features to restrict. + A space-delimited list of Portage features to restrict. Valid values are <c>fetch</c>, <c>mirror</c>, <c>strip</c>, <c>test</c> and <c>userpriv</c>. See <c>man 5 ebuild</c> for details. </ti> @@ -201,23 +341,31 @@ The following variables may or must be defined by every ebuild. <tr> <ti><c>DEPEND</c></ti> <ti> - A list of the package's build dependencies. See - <uri link="::general-concepts/dependencies"/>. + A list of the package's build dependencies. + See <uri link="::general-concepts/dependencies/"/>. + Starting with EAPI-7, applies to CHOST only. + </ti> + </tr> + <tr> + <ti><c>BDEPEND</c></ti> + <ti> + (EAPI=7) A list of the package's CBUILD build dependencies. + See <uri link="::general-concepts/dependencies/"/>. </ti> </tr> <tr> <ti><c>RDEPEND</c></ti> <ti> - A list of the package's runtime dependencies. See - <uri link="::general-concepts/dependencies"/>. + A list of the package's runtime dependencies. + See <uri link="::general-concepts/dependencies/"/>. </ti> </tr> <tr> <ti><c>PDEPEND</c></ti> <ti> A list of packages to be installed (if possible) after the package - is merged. Use this only when <c>RDEPEND</c> would cause cyclic - dependencies. See <uri link="::general-concepts/dependencies"/>. + is merged. Use this <e>only</e> when <c>RDEPEND</c> would cause cyclic + dependencies. See <uri link="::general-concepts/dependencies/"/>. </ti> </tr> <tr> @@ -230,102 +378,243 @@ The following variables may or must be defined by every ebuild. </ti> </tr> <tr> - <ti><c>PROPERTIES</c></ti> + <ti><c>DOCS</c></ti> <ti> - A space-delimited list of properties, with conditional - syntax support. <c>interactive</c> is the only valid value - for now. + An array or whitespace-separated list of documentation files for + the default <c>src_install</c> function to install using <c>dodoc</c>. + If undefined, a reasonable default list is used. See the + <uri link="::ebuild-writing/functions/src_install/#Default src_install"> + default <c>src_install</c> function</uri>. </ti> </tr> <tr> - <ti><c>DOCS</c></ti> + <ti><c>HTML_DOCS</c></ti> <ti> - An array or space-delimited list of documentation files for - the default src_install function to install using dodoc. If - undefined, a reasonable default list is used. (Requires - <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri>.) + An array or space-delimited list of documentation files or + directories for the <c>einstalldocs</c> function to install + recursively. (Requires + <uri link="::ebuild-writing/eapi/#EAPI 6">EAPI>=6</uri>.) </ti> </tr> </table> </body> -</section> -<section> -<title>SLOT</title> +<subsection> +<title>SRC_URI</title> + +<subsubsection> +<title>Conditional Sources</title> <body> <p> -When slots are not needed, use <c>SLOT="0"</c>. Do <b>not</b> use <c>SLOT=""</c>, as -this will disable slotting for this package. +Conditional source files based upon USE flags are allowed using the usual +<c>flag? ( )</c> syntax. This is often useful for arch-specific code or for binary +packages <d/> downloading sparc binaries on ppc would be a waste of bandwidth. </p> -<p> -See <uri link="::general-concepts/slotting/" /> for more information on this variable. -</p> +<codesample lang="ebuild"> +SRC_URI="https://example.com/files/${P}-core.tar.bz2 + x86? ( https://example.com/files/${P}/${P}-sse-asm.tar.bz2 ) + ppc? ( https://example.com/files/${P}/${P}-vmx-asm.tar.bz2 ) + sparc? ( https://example.com/files/${P}/${P}-vis-asm.tar.bz2 ) + doc? ( https://example.com/files/${P}/${P}-docs.tar.bz2 )" +</codesample> </body> -</section> +</subsubsection> -<section> -<title>KEYWORDS</title> +<subsubsection> +<title>Renaming Sources</title> <body> <p> -The only valid construct involving a <c>*</c> inside <c>KEYWORDS</c> is a <c>-*</c>. Do -<b>not</b> use <c>KEYWORDS="*"</c> or <c>KEYWORDS="~*"</c>. +Sometimes the upstream URI uses generic names that can easily clash with other +packages when creating a single mirror. Using the <c>-></c> syntax allows +you to rename the file when it's fetched from upstream for storing on mirrors +and in the local distdir. </p> <p> -See <uri link="::keywording/"/> for how to handle this variable. +Here we download a file from upstream which has a plain name like +<c>1.0.tar.gz</c> and save/mirror it with a better name like +<c>thepackage-1.0.tar.gz</c>. As usual, all tokens, including the operator +and the output file name, must be separated by whitespace. </p> -</body> -</section> +<codesample lang="ebuild"> +SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz" +</codesample> -<section> -<title>SRC_URI</title> +</body> +</subsubsection> -<subsection> -<title>Conditional Sources</title> +<subsubsection> +<title>Third-party mirrors</title> <body> <p> -Conditional source files based upon USE flags are allowed using the usual -<c>flag? ( )</c> syntax. This is often useful for arch-specific code or for binary -packages <d/> downloading sparc binaries on ppc would be a waste of bandwidth. +If the items in <c>SRC_URI</c> are available on multiple third-party mirrors, +and the same set of mirrors is shared across multiple ebuilds, then you +don't have to repeatedly list each of them in every ebuild. +The <c>profiles/thirdpartymirrors</c> file in the <c>::gentoo</c> repository +contains named groups of mirrors, in the format specified by the +Package Manager Specification (PMS), accessible through the +<c>mirror://</c> +pseudo-protocol. +</p> + +<p> +One might define a set of "example" mirrors, +</p> + +<pre> +example https://download.example.com https://mirror1.example.org/example +</pre> + +<p> +that can afterwards be referenced through a <c>mirror://</c> URI: </p> <codesample lang="ebuild"> -SRC_URI="http://example.com/files/${P}-core.tar.bz2 - x86? ( http://example.com/files/${P}/${P}-sse-asm.tar.bz2 ) - ppc? ( http://example.com/files/${P}/${P}-vmx-asm.tar.bz2 ) - sparc? ( http://example.com/files/${P}/${P}-vis-asm.tar.bz2 ) - doc? ( http://example.com/files/${P}/${P}-docs.tar.bz2 )" +SRC_URI="mirror://example/${PN}/${P}.tar.gz" </codesample> <p> -If a <c>USE_EXPAND</c> variable is used to control whether certain optional -components are installed, the correct thing to do if the variable is unset is -generally to install <e>all</e> available components. +There are two valid cases for using <c>thirdpartymirrors</c>: +</p> + +<ol> + <li> + providing multiple download locations for mirror- or fetch-restricted + packages, + </li> + + <li> + dealing with upstreams that distribute their distfiles via a network + of mirrors without a primary download location or a bouncer service. + </li> +</ol> + +<p> +In any other case, the primary location must be used instead. The distfiles +will be <uri link="::general-concepts/mirrors/">mirrored onto Gentoo +infrastructure</uri>; in that case, the benefit to using third-party mirror +list does not outweigh the burden of maintaining it. +</p> + +</body> +</subsubsection> + +<subsubsection> +<title>Lifting restrictions</title> +<body> + +<p> +In EAPI 8, individual items in <c>SRC_URI</c> can be exempted from automatic +mirroring and fetching restrictions (imposed by <c>RESTRICT="mirror"</c> and +<c>RESTRICT="fetch"</c>) by prefixing the addresses with <c>mirror+</c> or +<c>fetch+</c>. For example, in the following ebuild, </p> <codesample lang="ebuild"> -SRC_URI="http://example.com/files/${P}-core.tar.bz2 - examplecards_foo? ( http://example.com/files/${P}-foo.tar.bz2 ) - examplecards_bar? ( http://example.com/files/${P}-bar.tar.bz2 ) - examplecards_baz? ( http://example.com/files/${P}-baz.tar.bz2 ) - !examplecards_foo? ( !examplecards_bar? ( !examplecards_baz? ( - http://example.com/files/${P}-foo.tar.bz2 - http://example.com/files/${P}-bar.tar.bz2 - http://example.com/files/${P}-baz.tar.bz2 ) ) )" +EAPI="8" + +SRC_URI="${P}.tar.gz + mirror+https://dev.gentoo.org/~larry/distfiles/${P}-addons.tar.gz" + +RESTRICT="fetch" </codesample> +<p> +Portage will be prevented from trying to fetch <c>${P}.tar.gz</c> as expected, +but the <c>${P}-patches.tar.gz</c> file will be mirrored and fetched by Portage +without restriction. +</p> + +<p> +The following table shows the effects of the prefixes when <c>RESTRICT="mirror"</c> and <c>RESTRICT="fetch"</c> are set: +</p> + +<table> +<tr> + <th></th> + <th><e>(no prefix)</e></th> + <th><c>fetch+</c></th> + <th><c>mirror+</c></th> +</tr> +<tr> + <th><e>(no RESTRICT)</e></th> + <ti>fetch & mirror</ti> + <ti>fetch & mirror</ti> + <ti>fetch & mirror</ti> +</tr> +<tr> + <th><c>RESTRICT="mirror"</c></th> + <ti>fetch only</ti> + <ti>fetch only</ti> + <ti>fetch & mirror</ti> +</tr> +<tr> + <th><c>RESTRICT="fetch"</c></th> + <ti>unfetchable</ti> + <ti>fetch only</ti> + <ti>fetch & mirror</ti> +</tr> +</table> + </body> +</subsubsection> </subsection> -</section> -<section> +<subsection> +<title>LICENSE</title> +<body> + +<p> +It is possible to specify multiple <c>LICENSE</c> entries, and entries which only +apply if a particular <c>USE</c> flag is set. The format is the same as for +<c>DEPEND</c>. See <uri link="https://www.gentoo.org/glep/glep-0023.html"> +GLEP 23</uri> for details. +</p> + +</body> +</subsection> + +<subsection> +<title>SLOT</title> +<body> + +<p> +When slots are not needed, use <c>SLOT="0"</c>. Do <b>not</b> use +<c>SLOT=""</c>, because the variable must not be empty. +</p> + +<p> +See <uri link="::general-concepts/slotting/" /> for more information on this +variable and see <uri link="::ebuild-maintenance/package-moves/" />. +</p> + +</body> +</subsection> + +<subsection> +<title>KEYWORDS</title> +<body> + +<p> +The only valid construct involving a <c>*</c> inside <c>KEYWORDS</c> is a <c>-*</c>. Do +<b>not</b> use <c>KEYWORDS="*"</c> or <c>KEYWORDS="~*"</c>. +</p> + +<p> +See <uri link="::keywording/"/> for how to handle this variable. +</p> + +</body> +</subsection> + +<subsection> <title>IUSE</title> <body> @@ -338,24 +627,132 @@ You need not assign the IUSE variable in your ebuild if it is empty. </note> <p> -Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x86-fbsd</c> and so on) should not be -listed. +Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x64-macos</c> and so on) should +not be listed. </p> </body> +</subsection> + +<subsection> +<title>REQUIRED_USE</title> +<body> +<p> +The <c>REQUIRED_USE</c> variable contains a list of assertions that must be +met by the configuration of USE flags to be valid for this ebuild. In order +to be matched, a USE flag in a terminal element must be enabled +(or disabled if it has an exclamation mark prefix). +</p> + +<p> +Essentially, <c>REQUIRED_USE</c> is an analogue of <c>DEPEND</c> style syntax. +For example, to state that some combination is forbidden, i.e. "if foo is set, +bar must be unset": +</p> + +<codesample lang="ebuild"> +REQUIRED_USE="foo? ( !bar )" +</codesample> +<p> +To state "if foo is set, then at least one of bar, baz, and quux must be activated": +</p> +<codesample lang="ebuild"> +REQUIRED_USE="foo? ( || ( bar baz quux ) )" +</codesample> +<p> +To state "exactly one of foo, bar, or baz must be set, but not several": +</p> +<codesample lang="ebuild"> +REQUIRED_USE="^^ ( foo bar baz )" +</codesample> +<p> +Note that the last relationship is that of an Exclusive OR (XOR). +While an XOR could be formed from usual DEPEND syntax, +a specific ^^ operator has been added for this case. +</p> +<p> +Finally, to state "at least one of foo, bar, or baz must be set": +</p> +<codesample lang="ebuild"> +REQUIRED_USE="|| ( foo bar baz )" +</codesample> +<important> +See section <uri link="::general-concepts/use-flags/#Conflicting USE Flags"/> +for when (and when not) to use <c>REQUIRED_USE</c>. +</important> +</body> + +<subsubsection> +<title>EAPI 5</title> +<body> +<p> +EAPI 5 added an additional case to simplify conflicting USE flags. +</p> +<p> +To state "zero or one of foo, bar, or baz must be set, but not several": +</p> +<codesample lang="ebuild"> +REQUIRED_USE="?? ( foo bar baz )" +</codesample> +<p>In the previous EAPI, this would be the same as:</p> +<codesample lang="ebuild"> +REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )" +</codesample> +</body> +</subsubsection> +</subsection> + +<subsection> +<title>RESTRICT</title> +<body> + +<p> +While Portage may recognise several different <c>RESTRICT</c> tokens, it is +important that you do not rely on them existing. That is, you should ensure +your ebuild does not fail if those tokens are not exposed or given a different +name by another package manager. You can make use of Portage-provided +<c>RESTRICT</c> tokens, but do not fail hard without them. See +<uri link="https://projects.gentoo.org/pms/7/pms.html#x1-810008.2.8"> +PMS</uri> for the list of standardised <c>RESTRICT</c> tokens, or the above +table. +</p> + +</body> +</subsection> </section> <section> -<title>LICENSE</title> +<title>Variables reserved for the package manager</title> <body> <p> -It is possible to specify multiple <c>LICENSE</c> entries, and entries which only -apply if a particular <c>USE</c> flag is set. The format is the same as for -<c>DEPEND</c>. See <uri link="https://wiki.gentoo.org/wiki/GLEP:23"> -GLEP 23</uri> for details. +Variables and functions that begin with any of the following strings (ignoring +case) are reserved for package manager use. Ebuilds must neither use them nor +rely upon them: +</p> + +<ul> + <li><c>__</c> (two underscores)</li> + <li><c>abort</c></li> + <li><c>dyn</c></li> + <li><c>prep</c></li> +</ul> + +<p> +The same applies to functions and variables that contain any of the following +strings (ignoring case): </p> +<ul> + <li> + <c>ebuild</c> (unless immediately preceded by another letter, and except + for the <c>EBUILD_PHASE</c> and <c>EBUILD_PHASE_FUNC</c> variables) + </li> + <li><c>hook</c></li> + <li><c>paludis</c></li> + <li><c>portage</c></li> +</ul> + </body> </section> @@ -369,14 +766,19 @@ conventions. Using capital letters in names or differences in how underscores an are used in versions are particularly common. For example, what Gentoo calls <c>foo-1.2.3b</c> may be expecting a tarball named <c>Foo-1.2-3b.tar.bz2</c>. Rather than hard coding the package string, it is preferable to make <c>MY_PN</c>, <c>MY_PV</c> and <c>MY_P</c> variables and use those to define the -upstream naming. The easy way of redefining the version, which should be used unless you are sure -you know what you are doing, is to use the <c>versionator</c> eclass: +upstream naming. +EAPI=7 debuted a new set of functions, ver_cut, ver_rs and ver_test. +These were backported into older EAPIs with the <c>eapi7-ver</c> eclass. +The easy way of redefining the version, which should be used unless you are sure +you know what you are doing, is to use these functions: </p> <codesample lang="ebuild"> -inherit versionator +inherit eapi7-ver + MY_PN="Foo" -MY_PV=$(replace_version_separator 2 '-') +# Replace the second period separator in PV with - +MY_PV=$(ver_rs 2 '-') MY_P="${MY_PN}-${MY_PV}" </codesample> @@ -387,20 +789,21 @@ switches to a format like <c>Foo-1.3-4.5.tar.bz2</c> (yes, this really happens). <p> It is also possible to use bash substitution to achieve the same effect (this is -how versionator works internally), but this is complicated, error prone and hard +how eapi7-ver works internally), but this is complicated, error prone and hard to read. </p> <p> -Some ebuilds use calls to <c>sed</c>, <c>awk</c> and / or <c>cut</c> to do this. This -must <e>not</e> be done for any new code, and should be fixed to use either -versionator or bash substitution where possible. Global scope non-bash code is -highly discouraged. +Some ebuilds use calls to <c>sed</c>, <c>awk</c> and / or <c>cut</c> to do this. +This must <e>not</e> be done for any new code and should be fixed to use +built-in version manipulation commands (for EAPI 7 or later), Bash substitution, +or in older EAPIs before 7, <c>eapi7-ver</c>. Global scope non-Bash code is +<e>strongly</e> discouraged. </p> <p> -The <c>versionator</c> eclass can also be used to extract particular components -from a version string. See <c>man versionator.eclass</c> and the eclass source code +The ver_ functions are used extract particular components +from a version string. See <c>man eapi7-ver.eclass</c> and the eclass source code for further documentation and examples. A brief summary of the functions follows. </p> @@ -411,45 +814,282 @@ follows. <th>Purpose</th> </tr> <tr> - <ti><c>get_all_version_components</c></ti> - <ti>Split up a version string into its component parts.</ti> - </tr> - <tr> - <ti><c>get_version_components</c></ti> + <ti><c>ver_rs [range] ' '</c></ti> <ti>Get important version components, excluding '.', '-' and '_'.</ti> </tr> <tr> - <ti><c>get_major_version</c></ti> + <ti><c>ver_cut 1</c></ti> <ti>Get the major version.</ti> </tr> <tr> - <ti><c>get_version_component_range</c></ti> + <ti><c>ver_cut [range]</c></ti> <ti>Extract a range of subparts from a version string.</ti> </tr> <tr> - <ti><c>get_after_major_version</c></ti> + <ti><c>ver_cut 2-</c></ti> <ti>Get everything after the major version.</ti> </tr> <tr> - <ti><c>replace_version_separator</c></ti> + <ti><c>ver_rs [range] [char]</c></ti> <ti>Replace a particular version separator.</ti> </tr> <tr> - <ti><c>replace_all_version_separators</c></ti> + <ti><c>ver_rs 1- [char]</c></ti> <ti>Replace all version separators.</ti> </tr> <tr> - <ti><c>delete_version_separator</c></ti> + <ti><c>ver_rs [range] ''</c></ti> <ti>Delete a version separator.</ti> </tr> <tr> - <ti><c>delete_all_version_separators</c></ti> + <ti><c>ver_rs 1- ''</c></ti> <ti>Delete all version separators.</ti> </tr> </table> +<note> +A helpful guide to the newer complements of the old <c>versionator.eclass</c> +functions can be found +<uri link="https://mgorny.pl/articles/the-ultimate-guide-to-eapi-7.html#replacing-versionator-eclass-uses"> +here</uri>, courtesy of Gentoo developer mgorny. +</note> + </body> </section> +<section> +<title>Trailing Slashes in Variables</title> +<body> + +<p> +The following variables never end with a trailing slash in EAPI 7: +<c>D</c>, <c>ED</c>, <c>ROOT</c>, <c>EROOT</c>. Conversely, in EAPIs +preceeding EAPI 7, these variables are guaranteed to end with a +trailing slash. When working with EAPIs prior to EAPI 7, developers +are encouraged to use the bash suffix removal for the trailing slash +and add an explicit <c>/</c> when joining paths. For example: +<c>${D%/}/</c>, <c>${ED%/}/</c>, <c>${ROOT%/}/</c>, +<c>${EROOT%/}/</c>. +</p> + +</body> +</section> + +<section> +<title>Use of constant-value variables in ebuilds</title> +<body> + +<p> +Variables have significant value in ebuilds, making it possible to avoid +unnecessary repetitions and make maintenance easier. However, +references to constant-value variables should be used with care as their +excessive use can harm readability and increase maintenance burden (e.g. +when renaming a package). In particular, using variables whose values +have no direct correlation with the expected string should be avoided. +</p> + +<p>The examples of beneficial constant-value variable references are:</p> +<ul> + <li> + using <c>${PV}</c> and the variables derived from it (<c>${P}</c>, + <c>${MY_P}</c>…) in <c>SRC_URI</c> and <c>S</c> to avoid having + to update those variables for every version bump (assuming that + <c>${PV}</c> is used to indicate the upstream version); + </li> + + <li> + using <c>${PF}</c> in <c>--docdir</c> path — this is a canonical + Gentoo path that is always required to match <c>${PF}</c>. + </li> +</ul> + +<p>The examples of bad constant-value variable references are:</p> +<ul> + <li> + using <c>${PN}</c> in <c>HOMEPAGE</c>, <c>EGIT_REPO_URI</c> + or the domain of <c>SRC_URI</c> — it breaks URL parsing in editors + and terminals, and makes it hard to copy the link for external use + (e.g. while reviewing via gitweb), + </li> + + <li> + using <c>${HOMEPAGE}</c> in <c>SRC_URI</c> — it breaks when homepage + changes or additional entry is added, + </li> + + <li> + using <c>${PN}</c> (or other unnecessary helper variables) + excessively in <c>src_install()</c> — it impairs readability for + little benefit and causes a lot of trouble when the package needs to + be renamed. + </li> +</ul> + +</body> +</section> + +<section> +<title>User environment</title> +<body> + +<p> +The following variables may be set in the user's environment and should be +respected by all ebuilds. The purpose of each variable within Gentoo is listed +alongside an example of a valid value. Upstream usage may diverge, but ebuilds +should ensure that these variables are interpreted consistently within Gentoo. +The chosen meanings are inspired by a few real and de-facto standards: +</p> + +<ul> + <li> + <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html"> + The POSIX (2018) make specification</uri> + </li> + <li> + <uri link="https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html"> + The GNU make (v4.3) implementation</uri> + </li> + <li> + <uri link="https://www.gnu.org/software/libtool/manual/libtool.html#LT_005fINIT"> + The GNU libtool (v2.4.6) package</uri> + </li> +</ul> + +<p> +Many of these variables only have an effect if they are invoked directly. +For example, your compiler driver is usually responsible for assembling object +files rather than a direct call to <c>${AS}</c>. In that case, setting +<c>ASFLAGS</c> will have no effect on the build process; instead, you would set +something like <c>CFLAGS="-Wa,-alh,-L"</c> to tell the C compiler to pass those +flags to the assembler. The <c>LDFLAGS</c> variable is the exception to this +rule, as it is intended to be passed to the compiler driver rather than +<c>${LD}</c>. +</p> + +<table> + <tr> + <th>Variable</th> + <th>Purpose</th> + <th>Origin</th> + <th>Example</th> + </tr> + <tr> + <ti><c>AR</c></ti> + <ti> + <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/ar.html"> + ar</uri>-compatible library archiver + </ti> + <ti>POSIX make</ti> + <ti><c>x86_64-pc-linux-gnu-ar</c></ti> + </tr> + <tr> + <ti><c>ARFLAGS</c></ti> + <ti>flags for <c>${AR}</c></ti> + <ti>POSIX make</ti> + <ti><c>-v</c></ti> + </tr> + <tr> + <ti><c>AS</c></ti> + <ti>as-compatible assembler</ti> + <ti>GNU make</ti> + <ti><c>x86_64-pc-linux-gnu-as</c></ti> + </tr> + <tr> + <ti><c>ASFLAGS</c></ti> + <ti>flags for <c>${AS}</c></ti> + <ti>GNU make</ti> + <ti><c>--reduce-memory-overheads</c></ti> + </tr> + <tr> + <ti><c>CC</c></ti> + <ti>C compiler driver (also usually used for linking)</ti> + <ti>POSIX make</ti> + <ti><c>clang-9</c></ti> + </tr> + <tr> + <ti><c>CFLAGS</c></ti> + <ti>flags for <c>${CC}</c></ti> + <ti>POSIX make</ti> + <ti><c>-march=native</c></ti> + </tr> + <tr> + <ti><c>CPPFLAGS</c></ti> + <ti>flags for the C preprocessor</ti> + <ti>GNU make</ti> + <ti><c>-D_GNU_SOURCE</c></ti> + </tr> + <tr> + <ti><c>CXX</c></ti> + <ti>C++ compiler driver (also usually used for linking)</ti> + <ti>GNU make</ti> + <ti><c>clang++</c></ti> + </tr> + <tr> + <ti><c>CXXFLAGS</c></ti> + <ti>flags for <c>${CXX}</c></ti> + <ti>GNU make</ti> + <ti><c>-fvisibility=hidden</c></ti> + </tr> + <tr> + <ti><c>LD</c></ti> + <ti>dynamic linker</ti> + <ti>GNU libtool</ti> + <ti><c>x86_64-pc-linux-gnu-ld</c></ti> + </tr> + <tr> + <ti><c>LDFLAGS</c></ti> + <ti>flags for the <e>compiler driver</e> to pass to its linker</ti> + <ti>POSIX make</ti> + <ti><c>-Wl,-O1 -Wl,--as-needed</c></ti> + </tr> + <tr> + <ti><c>LEX</c></ti> + <ti> + <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/lex.html"> + lex</uri>-compatible lexer + </ti> + <ti>POSIX make</ti> + <ti><c>/usr/bin/flex</c></ti> + </tr> + <tr> + <ti><c>LFLAGS</c></ti> + <ti>flags for <c>${LEX}</c></ti> + <ti>POSIX make</ti> + <ti><c>--8bit --posix-compat</c></ti> + </tr> + <tr> + <ti><c>NM</c></ti> + <ti> + <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/nm.html"> + nm</uri>-compatible symbol extractor + </ti> + <ti>GNU libtool</ti> + <ti><c>x86_64-pc-linux-gnu-nm</c></ti> + </tr> + <tr> + <ti><c>RANLIB</c></ti> + <ti>archive index generator</ti> + <ti>GNU libtool</ti> + <ti><c>x86_64-pc-linux-gnu-ranlib</c></ti> + </tr> + <tr> + <ti><c>YACC</c></ti> + <ti> + <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/yacc.html"> + yacc</uri>-compatible compiler-compiler + </ti> + <ti>POSIX make</ti> + <ti><c>/usr/bin/bison</c></ti> + </tr> + <tr> + <ti><c>YFLAGS</c></ti> + <ti>flags for <c>${YACC}</c></ti> + <ti>POSIX make</ti> + <ti><c>-d</c></ti> + </tr> +</table> + +</body> +</section> </chapter> </guide> diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml index 1914448..23c7219 100644 --- a/eclass-writing/text.xml +++ b/eclass-writing/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="eclass-writing/"> <chapter> <title>Eclass Writing Guide</title> @@ -9,9 +9,11 @@ This section provides a brief introduction to eclass authoring. </p> <important> -You should reread the <uri link="::general-concepts/overlay#Overlay and Eclasses"/> -and <uri link="::general-concepts/portage-cache"/> sections before continuing. +You should reread the +<uri link="::general-concepts/overlay/#Overlay and Eclasses"/> +and <uri link="::general-concepts/portage-cache/"/> sections before continuing. </important> +</body> <section> <title>Purpose of Eclasses</title> @@ -26,15 +28,16 @@ Roughly speaking, there are three kinds of eclass: <ul> <li> Those which provide common functions which are used by many ebuilds (for - example, <c>eutils</c>, <c>versionator</c>, <c>cvs</c>, <c>bash-completion</c>) + example, <c>autotools</c>, <c>bash-completion-r1</c>, <c>flag-o-matic</c>, + <c>toolchain-funcs</c>) </li> <li> Those which provide a basic build system for many similar packages (for - example, <c>vim-plugin</c>, <c>kde</c>) + example, <c>perl-module</c>, <c>vim-plugin</c>) </li> <li> Those which handle one or a small number of packages with complex build - systems (for example, <c>vim</c>, <c>toolchain</c>, <c>kernel-2</c>) + systems (for example, <c>kernel-2</c>, <c>toolchain</c>) </li> </ul> @@ -46,47 +49,64 @@ Roughly speaking, there are three kinds of eclass: <body> <p> -Before committing a new eclass to the tree, it should be emailed to the -gentoo-dev mailing list with a justification and a proposed implementation. Do -not skip this step <d/> sometimes a better implementation or an alternative which +Before committing a new eclass to the tree, it must be emailed to the gentoo-dev +mailing list with a justification and a proposed implementation. Do not skip +this step <d/> sometimes a better implementation or an alternative which does not require a new eclass will be suggested. </p> <p> -Before updating <c>eutils</c> or a similar widely used eclass, it is best to email -the gentoo-dev list. It may be that your proposed change is broken in a way you -had not anticipated, or that there is an existing function which performs the -same purpose, or that your function may be better off in its own eclass. If you -don't email gentoo-dev first, and end up breaking something, expect to be in a -lot of trouble. +Before updating any eclass, email patches to the gentoo-dev list. It may be that +your proposed change is broken in a way you had not anticipated, or that there +is an existing function which performs the same purpose, or that your function +may be better off in its own eclass. If you don't email gentoo-dev first, +and end up breaking something, expect to be in a lot of trouble. </p> <p> -When removing a function or changing the API of an eclass, make -sure that it doesn't break any ebuilds in the tree, and post a -notice to gentoo-dev at least 30 days in advance, preferably with -a patch included. +Note that you should also, when sending your patch, CC any maintainers of the +eclass listed in the <c>@MAINTAINER</c> tag. You may want to contact them +ahead of time and get their opinions too. </p> <p> -If there is an existing maintainer for an eclass (this is usually the case), you -<b>must</b> talk to the maintainer before committing any changes. +The exceptions to this rule are updates to per-package eclasses. For example, +the <c>apache-2</c> eclass is only used by the <c>www-servers/apache</c> +package, and thus does not typically require changes to be emailed for review. </p> <p> -It is not usually necessary to email the gentoo-dev list before making changes -to a non-general eclass which you maintain. Use common sense here. +When removing a function or changing the API of an eclass, make sure that +it doesn't break any ebuilds in the Gentoo repository. Optionally, you may wish +to do a survey of some (official) overlays like <c>::guru</c>, <c>::musl</c>, or +<c>::science</c> in order to better understand how it is currently used and +<d/> where possible <d/> avoid breakage by pinging the maintainers directly. +</p> + +<p> +If there is an existing maintainer for an eclass (this is usually the case), you +<b>must</b> talk to the maintainer before committing any changes. </p> <warning> -Committing a broken eclass can kill huge numbers of packages. Since -<c>repoman</c> is not eclass-aware, be very sure you do proper testing. +Committing a broken eclass can kill huge numbers of packages. </warning> <p> A simple way to verify syntax is <c>bash -n foo.eclass</c>. </p> +<note> +Given that updating an eclass will invalidate the cache of all consumer ebuilds, +it is good etiquette to ping other developers in e.g. <c>#gentoo-dev</c> +on IRC or informally determine if there are other similar changes (mainly +documentation) which should be pushed at the same time in order to avoid +unnecessary cache regeneration within a few hours or days of each other. + +The same applies to your own work <d/> please prepare all of your commits and +batch push them at once where possible. +</note> + </body> </section> @@ -109,13 +129,55 @@ adhere to the following process:</p> </li> <li> Add a one line comment to the eclass, saying exactly <c># @DEAD</c> so that - the eclass-manpages package will not attempt to document it. + the eclass-manpages package will not attempt to document it. <c>@DEAD</c> + must be the first documentation tag in the eclass, i.e. it goes before + the <c>@ECLASS</c> tag. </li> <li> Wait for the 30-day period to pass, then remove the eclass from the tree. </li> </ol> +<note> +Before considering removal, please mark the eclass as <c># @DEPRECATED:</c> +to ensure consumers are warned if they are still using the eclass. Do this +for a period before removing the eclass. +</note> + +</body> +</section> + +<section> +<title>Documenting Eclasses</title> +<body> + +<p> +Eclasses are documented with comment blocks that follow a special +markup syntax. The comment blocks are separated by blank lines and +each block documents an individual element of an eclass. +</p> + +<p> +Documentation tags for various eclass elements are explained in their +respective sections below. Common to all the tags that accept multiline +freetext, the <c>@CODE</c> tag should be used when necessary to create +unformatted code chunks (such as example code) by placing the tag at the +beginning and the end. The <c>@SUBSECTION</c> tag inserts a subsection +heading; it is allowed only in the main <c>@DESCRIPTION</c>. +</p> + +<p> +Note that <c>pkgcheck</c> can check for issues in eclass documentation. +You could run e.g. <c>pkgcheck scan -s eclass</c> to check for issues +in the tree or <c>pkgcheck scan --commits</c> to check for issues +in your staged git commits. +</p> + +<note> +In eclass documentation, two spaces should be used after the end of each +sentence (unless it is followed by a newline). This will help <c>groff</c> +to properly break lines when generating eclass manpages. +</note> </body> </section> @@ -132,11 +194,103 @@ underscores and dots. Eclasses are not intrinsically versioned. </p> <p> -Eclasses should start with the standard ebuild header, along with comments -explaining the maintainer and purpose of the eclass, and any other relevant -documentation. +Eclasses should start with the standard ebuild header, along with +comments explaining the maintainer and purpose of the eclass, and any +other relevant documentation. Eclass documentation block should be the +first documentation block to appear in the eclass. The following table +summarizes the available documentation tags: </p> +<table> +<tr> + <th>tag</th> + <th>required?</th> + <th>arguments</th> + <th>description</th> +</tr> +<tr> + <ti><c>@ECLASS:</c></ti> + <ti>Yes</ti> + <ti>Name of the eclass being documented</ti> + <ti> + Documents various information about the eclass. Must appear as the + first tag in the comment block. + </ti> +</tr> +<tr> + <ti><c>@MAINTAINER:</c></ti> + <ti>Yes</ti> + <ti>One or more name and email pairs</ti> + <ti> + List of maintainers for the eclass to be contacted. One line per + maintainer. Must start on a newline after the tag. + </ti> +</tr> +<tr> + <ti><c>@AUTHOR:</c></ti> + <ti>No</ti> + <ti>One or more name and email pairs</ti> + <ti> + List of authors for the eclass. One line per author. Must start on + a newline after the tag. + </ti> +</tr> +<tr> + <ti><c>@BUGREPORTS:</c></ti> + <ti>No</ti> + <ti>Multiline freetext</ti> + <ti>Describes how bugs related to this eclass should be reported</ti> +</tr> +<tr> + <ti><c>@VCSURL:</c></ti> + <ti>No</ti> + <ti>A URI string</ti> + <ti>Points to the URL of the VCS that contains the eclass source</ti> +</tr> +<tr> + <ti nowrap="nowrap"><c>@SUPPORTED_EAPIS:</c></ti> + <ti>No</ti> + <ti>Space-separated list of EAPIs</ti> + <ti>List of EAPIs supported by this eclass</ti> +</tr> +<tr> + <ti><c>@PROVIDES:</c></ti> + <ti>No</ti> + <ti>Space-separated list of eclass names</ti> + <ti> + List of indirectly inherited eclasses whose functions and variables may be + used by an ebuild inheriting this eclass + </ti> +</tr> +<tr> + <ti><c>@BLURB:</c></ti> + <ti>Yes</ti> + <ti>Single line freetext</ti> + <ti> + Contains a short description for the eclass. Must be on the same + line with the tag. + </ti> +</tr> +<tr> + <ti><c>@DEPRECATED:</c></ti> + <ti>No</ti> + <ti>Replacement (or "none")</ti> + <ti>Declares that this eclass should no longer be used</ti> +</tr> +<tr> + <ti><c>@DESCRIPTION:</c></ti> + <ti>No</ti> + <ti>Multiline freetext</ti> + <ti>Long description for the eclass</ti> +</tr> +<tr> + <ti><c>@EXAMPLE:</c></ti> + <ti>No</ti> + <ti>Multiline freetext</ti> + <ti>Examples that illustrate various uses of this eclass</ti> +</tr> +</table> + </body> </section> @@ -150,6 +304,94 @@ used, <c>IUSE</c> must be set. The <c>KEYWORDS</c> variable must <b>not</b> be s eclass. </p> +<p> +You should document the meaning, usage, and default value of every +variable in your eclass. The tags available for documenting eclass +variables are as follows: +</p> + +<table> +<tr> + <th>tag</th> + <th>required?</th> + <th>arguments</th> + <th>description</th> +</tr> +<tr> + <ti nowrap="nowrap"><c>@ECLASS_VARIABLE:</c></ti> + <ti>Yes</ti> + <ti>Name of the eclass variable to which the documentation applies</ti> + <ti> + This tag applies to eclass specific variables that affect the + default behavior of the eclass. Read-only variables, which are + exported by the eclass for developer use, are also documented with + this tag. Must appear as the first tag in the comment block. + </ti> +</tr> +<tr> + <ti><c>@PRE_INHERIT</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti> + This tag describes whether the variable must be defined before + the eclass is inherited. This is important if any e.g. dependencies + are modified in global scope at the point of sourcing. + </ti> +</tr> +<tr> + <ti><c>@USER_VARIABLE</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti> + This tag describes whether the variable is unsuitable for use in ebuilds, + i.e. if it is solely for user consumption via e.g. make.conf or a similar + mechanism + </ti> +</tr> +<tr> + <ti><c>@OUTPUT_VARIABLE</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti> + This tag indicates that the variable's value (which will be set by the + eclass) should be read within an ebuild + </ti> +</tr> +<tr> + <ti><c>@DEFAULT_UNSET</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti> + Indicates that this variable is unset by default if not set by the + developer + </ti> +</tr> +<tr> + <ti><c>@INTERNAL</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti>Indicates that the variable is internal to the eclass</ti> +</tr> +<tr> + <ti><c>@REQUIRED</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti>Indicates that this variable must be set by the developer</ti> +</tr> +<tr> + <ti><c>@DEPRECATED:</c></ti> + <ti>No</ti> + <ti>Optionally, the name of any replacement variable</ti> + <ti>Declares that this variable should no longer be used in ebuilds</ti> +</tr> +<tr> + <ti><c>@DESCRIPTION:</c></ti> + <ti>Yes</ti> + <ti>Multiline freetext</ti> + <ti>Long description for the eclass variable</ti> +</tr> +</table> + </body> </section> @@ -162,6 +404,158 @@ Eclasses may define functions. These functions will be visible to anything which inherits the eclass. </p> +<p> +You should document the purpose, arguments, usage, and return value of +every function in your eclass. The standard tags available for +documentation are: +</p> + +<table> +<tr> + <th>tag</th> + <th>required?</th> + <th>arguments</th> + <th>description</th> +</tr> +<tr> + <ti><c>@FUNCTION:</c></ti> + <ti>Yes</ti> + <ti>Name of the function to which the documentation block applies</ti> + <ti> + Documents information about an eclass function such as its calling + convention etc. Must appear as the first tag in the comment block + </ti> +</tr> +<tr> + <ti><c>@USAGE:</c></ti> + <ti>No</ti> + <ti>List of required and optional arguments to the function</ti> + <ti> + List of arguments that the eclass function accepts, specified in + the following syntax: <c><</c>Required arguments<c>></c> + <c>[</c>Optional arguments<c>]</c> + </ti> +</tr> +<tr> + <ti><c>@RETURN:</c></ti> + <ti><b>*</b></ti> + <ti>Return value of the function</ti> + <ti> + <p>Description for the value returned by the function.</p> + <p><b>*</b>: Required for functions that return a value.</p> + </ti> +</tr> +<tr> + <ti><c>@MAINTAINER:</c></ti> + <ti>No</ti> + <ti>Multiline freetext</ti> + <ti> + List of contacts for the eclass function. One line per + maintainer. Must start on a newline after the tag. + </ti> +</tr> +<tr> + <ti><c>@INTERNAL</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti> + Indicates that the function is internal to the eclass and should + not be called from outside + </ti> +</tr> +<tr> + <ti><c>@DEPRECATED:</c></ti> + <ti>No</ti> + <ti>Optionally, the name of a replacement function</ti> + <ti>Declares that this function should no longer be used in ebuilds</ti> +</tr> +<tr> + <ti><c>@DESCRIPTION:</c></ti> + <ti><b>*</b></ti> + <ti>Multiline freetext</ti> + <ti> + <p>Long description for the eclass function.</p> + <p><b>*:</b> Required if <c>RETURN:</c> is absent.</p> + </ti> +</tr> +</table> + +</body> +</section> +<section> +<title>Eclass Function Variables</title> +<body> + +<p> +Eclass functions may make use of variables just like any other bash +function. Special function-specific variables should be documented +using the following tags: +</p> + +<table> +<tr> + <th>tag</th> + <th>required?</th> + <th>arguments</th> + <th>description</th> +</tr> +<tr> + <ti><c>@VARIABLE:</c></ti> + <ti>Yes</ti> + <ti> + Name of the function-specific variable to which the documentation applies + </ti> + <ti> + This tag applies to variables consumed by specific functions of + the eclass. They are in effect only when the specific function is + called. + </ti> +</tr> +<tr> + <ti><c>@USER_VARIABLE</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti> + This tag describes whether the variable is unsuitable for use in ebuilds, + i.e. if it is solely for user consumption via e.g. make.conf or a similar + mechanism + </ti> +</tr> +<tr> + <ti><c>@DEFAULT_UNSET</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti> + Indicates that this variable is unset by default if not set by the + developer + </ti> +</tr> +<tr> + <ti><c>@INTERNAL</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti>Indicates that the variable is internal to the eclass function</ti> +</tr> +<tr> + <ti><c>@REQUIRED</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti>Indicates that this variable must be set by the developer</ti> +</tr> +<tr> + <ti><c>@DEPRECATED:</c></ti> + <ti>No</ti> + <ti>Optionally, the name of any replacement variable</ti> + <ti>Declares that this variable should no longer be used in ebuilds</ti> +</tr> +<tr> + <ti><c>@DESCRIPTION:</c></ti> + <ti>Yes</ti> + <ti>Multiline freetext</ti> + <ti>Long description for the function variable</ti> +</tr> +</table> + </body> </section> @@ -176,26 +570,26 @@ a single function, <c>domacosapp</c>. </p> <codesample lang="ebuild"> -# Copyright 1999-2005 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -# -# Original Author: Ciaran McCreesh <ciaranm@gentoo.org> -# Purpose: install macos .app files to the relevant location. -# -# Bugs to osx@gentoo.org -# - -# domacosapp: install a macos .app file. Usage is 'domacosapp file' or -# 'domacosapp file newfile'. +# @ECLASS: macosapp.eclass +# @MAINTAINER: +# Ciaran McCreesh <ciaranm@gentoo.org> +# @BLURB: install macos .app files to the relevant location. + +# @FUNCTION: domacosapp +# @USAGE: <app-file> [new-file] +# @DESCRIPTION: +# Install the given .app file into the appropriate location. If +# [new-file] is given, it will be used as the new (installed) name of +# the file. Otherwise <app-file> is installed as-is. domacosapp() { - [[ -z "${1}" ]] && die "usage: domacosapp <file> <new file>" - if use ppc-macos ; then - insinto /Applications - newins "$1" "${2:-${1}}" || die "Failed to install ${1}" - fi + [[ -z "${1}" ]] && die "usage: domacosapp <file> [new file]" + if use ppc-macos ; then + insinto /Applications + newins "$1" "${2:-${1}}" + fi } </codesample> @@ -207,15 +601,15 @@ domacosapp() { <body> <p> -An eclass may provide default implementations for any of the standard ebuild -functions (<c>src_unpack</c>, <c>pkg_postinst</c> etc). This can be done either as a +An eclass may provide default implementations for any of the ebuild phase +functions (<c>src_unpack</c>, <c>pkg_postinst</c>, etc). This can be done either as a simple function definition (which is not multiple eclass friendly) or using <c>EXPORT_FUNCTIONS</c>. Functions given to <c>EXPORT_FUNCTIONS</c> are implemented -as normal, but have their name prefixed with <c>${ECLASS}_</c>. +as normal, but have their name prefixed ("namespaced") with <c>${ECLASS}_</c>. </p> <important> -Only 'standard' functions should be specified in <c>EXPORT_FUNCTIONS</c>. +Only the ebuild phase functions may be specified in <c>EXPORT_FUNCTIONS</c>. </important> <note><c>EXPORT_FUNCTIONS</c> is a function, <e>not</e> a variable.</note> @@ -228,11 +622,11 @@ eclass-defined defaults <d/> for example, say we had <c>fnord.eclass</c>: </p> <codesample lang="ebuild"> -EXPORT_FUNCTIONS src_compile - fnord_src_compile() { - do_stuff || die + do_stuff || die } + +EXPORT_FUNCTIONS src_compile </codesample> <p> @@ -240,55 +634,93 @@ Then an ebuild could do this: </p> <codesample lang="ebuild"> -inherit fnord.eclass +inherit fnord src_compile() { - do_pre_stuff || die - fnord_src_compile - do_post_stuff || die + do_pre_stuff || die + fnord_src_compile + do_post_stuff || die } </codesample> +<p> +Eclasses may inherit other eclasses to make use of their functionality, and +historically there have been instances of eclasses calling +<c>EXPORT_FUNCTIONS</c> and then inheriting another eclass. As inherited +eclasses may also execute <c>EXPORT_FUNCTIONS</c>, it was not fully defined +which defaults should take effect. The general recommendation is now that +eclasses should not inherit other eclasses <e>after</e> calling +<c>EXPORT_FUNCTIONS</c>. +</p> + </body> </section> <section> -<title>Simple Build System Eclass Example</title> +<title>Inherit guards</title> <body> <p> -A simple eclass which defines a number of functions and a default -<c>src_compile</c> for the (hypothetical) <c>jmake</c> build system might look -something like the following: +It is common practice to surround the main contents of an eclass with an +"inherit guard". Much like header guards known from C, inherit guards help +ensure that an eclass can be inherited multiple times and have its functions and +variables defined only once. An inherit guard is only needed for an eclass that +can be inherited more than once. +</p> + +<p> +A typical inherit guard looks as follows (for a hypothetical <c>foo.eclass</c>): </p> <codesample lang="ebuild"> -# Copyright 1999-2005 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 -# $Header: $ +if [[ -z ${_FOO_ECLASS} ]]; then +_FOO_ECLASS=1 -# Original Author: Ciaran McCreesh <ciaranm@gentoo.org> -# Purpose: Demonstration of EXPORT_FUNCTIONS. Defines simple wrappers for the -# (hypothetical) 'jmake' build system and a default src_compile. +# Variables and functions go here -EXPORT_FUNCTIONS src_compile +fi +</codesample> -DEPEND=">=sys-devel/jmake-2" +<p> +When it comes to <c>EXPORT_FUNCTIONS</c> and inherit guards, the call to +<c>EXPORT_FUNCTIONS</c> must be placed at the very end of the eclass +<e>outside</e> any inherit guards, like this: +</p> -jmake-configure() { - jmake configure --prefix=/usr "$@" -} +<codesample lang="ebuild"> +if [[ -z ${_FOO_ECLASS} ]]; then +_FOO_ECLASS=1 -jmake-build() { - jmake dep && jmake build "$@" +foo_src_compile() { + ... } +fi -jmake_src_compile() { - jmake-configure || die "configure failed" - jmake-build || die "build failed" -} +EXPORT_FUNCTIONS src_compile </codesample> +<p> +This helps to ensure that the last inherited eclass gets to define the default +phase functions. Consider two eclasses <c>foo.eclass</c> and <c>bar.eclass</c> +that define the same default phase function via <c>EXPORT_FUNCTIONS</c>. If an +ebuild inherits both as <c>inherit foo bar</c>, then the default phases are +defined by <c>bar.eclass</c>. If <c>foo.eclass</c> is then modified to inherit +<c>bar</c> as well, then the ebuild's default functions could suddenly become +those from <c>foo</c> if <c>EXPORT_FUNCTIONS</c> was placed inside the inherit +guard. +</p> + +<note> +The rule of thumb here is: put the call (if any) to <c>EXPORT_FUNCTIONS</c> in +the last line of an eclass, outside of any inherit guards. +</note> + +<warning> +Old eclasses may put <c>EXPORT_FUNCTIONS</c> in other places, even before +<c>inherit</c>. They should <e>not</e> blindly be updated to follow the +recommended pattern here, as it could result in significant breakage. +</warning> + </body> </section> @@ -298,29 +730,108 @@ jmake_src_compile() { <p> Sometimes an eclass is used incorrectly by an ebuild and the eclass -knows it is being used incorrectly- the common example is an +knows it is being used incorrectly <d/> the common example is an eclass that only works with a specific set of EAPIs, but is being -accessed inherited by an ebuild with a different EAPI. +accessed (inherited) by an ebuild with a different EAPI. In those cases, used sparingly as a last resort, it is allowed for an eclass to invoke die from the global scope. For example: </p> <codesample lang="ebuild"> -# Copyright 1999-2010 Gentoo Foundation +# Copyright 1999-2022 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -# Purpose: Demonstration of die upon invalid EAPI usage. +# @ECLASS: eapi-die.eclass +# @MAINTAINER: +# Gentoo Devmanual Project <devmanual@gentoo.org> +# @SUPPORTED_EAPIS: 7 8 +# @BLURB: Calls die when used with an invalid EAPI. -case ${EAPI:-0} in - 0) die "this eclass doesn't support EAPI 0" ;; - *) ;; +case ${EAPI} in + 7|8) ;; + *) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;; esac </codesample> </body> </section> +<section> +<title>Simple Build System Eclass Example</title> +<body> + +<p> +Here is an example of how a simple eclass for a hypothetical <c>jmake</c> build +system might look. The eclass defines a few functions, along with default +implementations for the <c>src_configure</c> and <c>src_compile</c> phase +functions. +</p> + +<codesample lang="ebuild"> +# Copyright 1999-2022 Gentoo Authors +# Distributed under the terms of the GNU General Public License v2 + +# @ECLASS: jmake.eclass +# @MAINTAINER: +# Gentoo Devmanual Project <devmanual@gentoo.org> +# @AUTHOR: +# Ciaran McCreesh <ciaranm@gentoo.org> +# @BLURB: Demonstrate a simple build system eclass. +# @DESCRIPTION: +# Demonstrates EXPORT_FUNCTIONS and defines simple wrappers for the +# (hypothetical) jmake build system along with default src_configure and +# src_compile phase functions. + +case ${EAPI} in + 7|8) ;; + *) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;; +esac + +if [[ -z ${_JMAKE_ECLASS} ]]; then +_JMAKE_ECLASS=1 + +BDEPEND=">=sys-devel/jmake-2" + +# @FUNCTION: jmake-configure +# @USAGE: [additional-args] +# @DESCRIPTION: +# Passes all arguments through to the appropriate "jmake configure" +# command. +jmake_configure() { + jmake configure --prefix=/usr "$@" +} + +# @FUNCTION: jmake_src_configure +# @USAGE: [additional-args] +# @DESCRIPTION: +# Calls jmake_configure() to configure a jmake project. Passes all +# arguments through to the appropriate "jmake configure" command. +jmake_src_configure() { + jmake_configure "$@" || die "configure failed" +} + +# @FUNCTION: jmake_build +# @USAGE: [additional-args] +# @DESCRIPTION: +# First builds all dependencies, and then passes through its arguments +# to the appropriate "jmake build" command. +jmake_build() { + jmake dep && jmake build "$@" +} + +# @FUNCTION: jmake_src_compile +# @DESCRIPTION: +# Calls jmake_build() to compile a jmake project. +jmake_src_compile() { + jmake_build || die "build failed" +} + +fi + +EXPORT_FUNCTIONS src_configure src_compile +</codesample> + </body> +</section> </chapter> </guide> diff --git a/function-reference/build-functions/text.xml b/function-reference/build-functions/text.xml index dd14233..5d5b6ab 100644 --- a/function-reference/build-functions/text.xml +++ b/function-reference/build-functions/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/build-functions/"> <chapter> <title>Build Functions Reference</title> @@ -32,7 +32,10 @@ during the unpack and compile stages. <c>econf args</c> </ti> <ti> - Wrapper for <c>./configure</c>. Passes on all <c>args</c>. Will abort (via <c>die</c>) should <c>configure</c> fail. + Wrapper for <c>./configure</c>. Passes on all <c>args</c>. Will abort + (via <c>die</c>) should <c>configure</c> fail. + See <uri link="::ebuild-writing/functions/src_configure/configuring/#econf Options"/> + for details. </ti> </tr> <tr> @@ -43,14 +46,6 @@ during the unpack and compile stages. Wrapper for <c>make</c>. Passes on all <c>args</c>. </ti> </tr> - <tr> - <ti> - <c>einstall args</c> - </ti> - <ti> - Wrapper for <c>emake install</c>, only to be used if <c>emake DESTDIR="${D}"</c> is unsuitable. - </ti> - </tr> </table> </body> diff --git a/function-reference/error-functions/text.xml b/function-reference/error-functions/text.xml new file mode 100644 index 0000000..272784e --- /dev/null +++ b/function-reference/error-functions/text.xml @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="function-reference/error-functions/"> +<chapter> +<title>Error Functions Reference</title> +<body> + +<p> +The following functions are provided by the package manager for error handling. +</p> + +<table> + <tr> + <th>Function</th> + <th>Details</th> + </tr> + <tr> + <ti><c>die</c></ti> + <ti> + <p> + Displays an error message provided in its argument, and aborts the build + process. + </p> + <p> + In EAPI 6 and later, <c>die</c> can be called under the <c>nonfatal</c> + command and with the <c>-n</c> option, in which case it will not abort + the build process, but return with non-zero status. + </p> + </ti> + </tr> + <tr> + <ti><c>assert</c></ti> + <ti> + Checks the value of the <c>PIPESTATUS</c> array, and calls <c>die</c> + if any of its component is non-zero (which indicates failure of the + preceding command pipeline). + </ti> + </tr> + <tr> + <ti><c>nonfatal</c></ti> + <ti> + Takes another command as its argument and executes it. If the command + fails and would normally die, it returns with non-zero status instead + when called under <c>nonfatal</c>. + </ti> + </tr> +</table> + +</body> +</chapter> +</guide> diff --git a/function-reference/install-functions/text.xml b/function-reference/install-functions/text.xml index 1feb198..0d37980 100644 --- a/function-reference/install-functions/text.xml +++ b/function-reference/install-functions/text.xml @@ -1,13 +1,12 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/install-functions/"> <chapter> <title>Install Functions Reference</title> <body> <p> -The following functions, which are all provided by <c>ebuild.sh</c> and the standard -library, handle various install-related tasks. <c>${D}</c> is automatically handled -for all of these functions. +The following functions are provided by the package manager to handle various +install-related tasks. <c>${ED}</c> is prepended automatically to the install location. </p> <p> @@ -16,6 +15,10 @@ targets. The <c>new*</c> functions take exactly two arguments (except as noted) the first is the source name, the second the name to use when installing. </p> +<p> +The <c>*into</c> functions create the directory if it does not already exist. +</p> + <table> <tr> <th> @@ -33,9 +36,9 @@ the first is the source name, the second the name to use when installing. Change install location for <c>dobin</c>, <c>newbin</c>, <c>dosbin</c>, <c>newsbin</c>, - <c>doman</c>, <c>newman</c>, - <c>doinfo</c>, <c>newinfo</c>, - <c>dolib</c>, <c>newlib</c> + <c>dolib</c>, + <c>dolib.a</c>, <c>newlib.a</c>, + <c>dolib.so</c>, <c>newlib.so</c> </ti> </tr> <tr> @@ -67,7 +70,7 @@ the first is the source name, the second the name to use when installing. <c>insopts</c> </ti> <ti> - Specify arguments passed to <c>install</c> (eg <c>-s</c>, <c>-m644</c>). + Specify arguments passed to <c>install</c> (eg <c>-s</c>, <c>-m644</c>) </ti> </tr> <tr> @@ -92,6 +95,7 @@ the first is the source name, the second the name to use when installing. </ti> <ti> Specify arguments passed to <c>install</c> for libraries + <b>Note:</b> Banned in EAPI=7 </ti> </tr> <tr> @@ -99,7 +103,10 @@ the first is the source name, the second the name to use when installing. <c>dobin</c> </ti> <ti> - Install a binary + Install a binary into subdirectory <c>bin</c> of the location provided + by <c>into</c> (resulting in <c>/usr/bin</c> by default) with mode 0755 + and with ownership set to superuser or its equivalent on the system or + installation at hand </ti> </tr> <tr> @@ -115,7 +122,9 @@ the first is the source name, the second the name to use when installing. <c>dodir</c> </ti> <ti> - Install a directory + Install a directory that will be non-empty when the package is + merged. For directories that will be empty, please use + <c>keepdir</c> instead. </ti> </tr> <tr> @@ -123,7 +132,19 @@ the first is the source name, the second the name to use when installing. <c>dodoc</c> </ti> <ti> - Install a documentation file + Install a documentation file into <c>/usr/share/doc/${PF}</c>. + The <c>-r</c> option allows directories to be installed recursively. + </ti> + </tr> + <tr> + <ti> + <c>einstalldocs</c> + </ti> + <ti> + Installs the files and directories specified by the <c>DOCS</c> + and <c>HTML_DOCS</c> variables into <c>/usr/share/doc/${PF}</c> + recursively using <c>dodoc -r</c>. <b>Note</b>: Approved in EAPI + 6. </ti> </tr> <tr> @@ -139,15 +160,18 @@ the first is the source name, the second the name to use when installing. <c>doexe</c> </ti> <ti> - Install an executable + Install an executable into the location provided by <c>exeinto</c>, + by default with mode 0755 or with the install options set by + <c>exeopts</c> </ti> </tr> <tr> <ti> - <c>dohard</c> + <c>doheader</c> </ti> <ti> - Create a hardlink to the first argument from the second argument + Install a header file into <c>/usr/include</c>. + The <c>-r</c> option allows directories to be installed recursively. </ti> </tr> <tr> @@ -156,6 +180,10 @@ the first is the source name, the second the name to use when installing. </ti> <ti> Installs HTML document files into <c>/usr/share/doc/${PF}/html</c> + The <c>-r</c> option allows directories to be installed recursively. + <b>Note</b>: Deprecated in EAPI 6, switch to <c>einstalldocs</c> + instead. + <b>Note:</b> Banned in EAPI=7 </ti> </tr> <tr> @@ -179,7 +207,10 @@ the first is the source name, the second the name to use when installing. <c>doins</c> </ti> <ti> - Install a miscellaneous file + Install a miscellaneous file. + The <c>-r</c> option allows directories to be installed recursively. + Any symlinks encountered are installed as symlinks, when installing + recursively. </ti> </tr> <tr> @@ -188,6 +219,7 @@ the first is the source name, the second the name to use when installing. </ti> <ti> Install a library file + <b>Note:</b> Banned in EAPI=7 </ti> </tr> <tr> @@ -211,7 +243,17 @@ the first is the source name, the second the name to use when installing. <c>doman</c> </ti> <ti> - Install a man page + <p> + Install a man page into the appropriate section of <c>/usr/share/man</c>. + e.g., <c>foo.1</c> will be installed in <c>/usr/share/man/man1/foo.1</c>. + </p> + <p> + If the man page is named <c>foo.<lang>.1</c> then it will be + installed in <c>/usr/share/man/<lang>/man1/foo.1</c>, where + <c><lang></c> is a language code. Option <c>-i18n=<lang></c> + can be used to explicitly specify a subdirectory (or to suppress it, if + empty). + </p> </ti> </tr> <tr> @@ -219,7 +261,8 @@ the first is the source name, the second the name to use when installing. <c>domo</c> </ti> <ti> - Install a Gettext <c>.mo</c> file + Install a Gettext <c>.mo</c> file. + (EAPI=7) No longer looks at the value of <c>into</c> </ti> </tr> <tr> @@ -235,7 +278,16 @@ the first is the source name, the second the name to use when installing. <c>dosym</c> </ti> <ti> - Create a symlink from the second parameter to the first parameter + <p> + Create a symlink to the target specified as the first parameter, at the + path specified by the second parameter. With option <c>-r</c> (EAPI 8), + an absolute path specified for the target will be converted to a path + relative to the link location. + </p> + <p> + Note: Without option <c>-r</c>, an absolute link target is interpreted + <e>verbatim</e>, i.e. it must include <c>${EPREFIX}</c> when applicable. + </p> </ti> </tr> <tr> @@ -243,7 +295,7 @@ the first is the source name, the second the name to use when installing. <c>fowners</c> </ti> <ti> - Call <c>chown</c> on the specified files in <c>${D}</c> + Call <c>chown</c> on the specified files in <c>${ED}</c> </ti> </tr> <tr> @@ -251,7 +303,7 @@ the first is the source name, the second the name to use when installing. <c>fperms</c> </ti> <ti> - Call <c>chmod</c> on the specified files in <c>${D}</c> + Call <c>chmod</c> on the specified files in <c>${ED}</c> </ti> </tr> <tr> @@ -259,7 +311,15 @@ the first is the source name, the second the name to use when installing. <c>keepdir</c> </ti> <ti> - Create a directory with an empty <c>.keep</c> file in it. + Install a directory that will be empty when the package is + merged. This is like <c>dodir</c>, but for empty directories + instead. <uri + link="https://projects.gentoo.org/pms/7/pms.html#x1-14200013.2.2">The + handling of empty directories is undefined by the package + manager specification</uri>, and the <c>keepdir</c> function + exists to ensure that the (otherwise empty) directory is + tracked. This is accomplished by installing a hidden file + prefixed with <c>.keep</c> to the directory in question. </ti> </tr> <tr> @@ -267,7 +327,7 @@ the first is the source name, the second the name to use when installing. <c>newbin</c> </ti> <ti> - Install a binary using the second argument as the name. + Install a binary using the second argument as the name </ti> </tr> <tr> @@ -275,7 +335,7 @@ the first is the source name, the second the name to use when installing. <c>newconfd</c> </ti> <ti> - Install an <c>/etc/conf.d</c> entry using the second argument as the name. + Install an <c>/etc/conf.d</c> entry using the second argument as the name </ti> </tr> <tr> @@ -283,7 +343,7 @@ the first is the source name, the second the name to use when installing. <c>newdoc</c> </ti> <ti> - Install a documentation file using the second argument as the name. + Install a documentation file using the second argument as the name </ti> </tr> <tr> @@ -291,7 +351,7 @@ the first is the source name, the second the name to use when installing. <c>newenvd</c> </ti> <ti> - Install an <c>/etc/env.d</c> file using the second argument as the name. + Install an <c>/etc/env.d</c> file using the second argument as the name </ti> </tr> <tr> @@ -299,7 +359,15 @@ the first is the source name, the second the name to use when installing. <c>newexe</c> </ti> <ti> - Install an executable file using the second argument as the name. + Install an executable file using the second argument as the name + </ti> + </tr> + <tr> + <ti> + <c>newheader</c> + </ti> + <ti> + Install a header file using the second argument as the name </ti> </tr> <tr> @@ -307,7 +375,7 @@ the first is the source name, the second the name to use when installing. <c>newinitd</c> </ti> <ti> - Install an <c>/etc/init.d</c> file using the second argument as the name. + Install an <c>/etc/init.d</c> file using the second argument as the name </ti> </tr> <tr> @@ -315,7 +383,7 @@ the first is the source name, the second the name to use when installing. <c>newins</c> </ti> <ti> - Install a miscellaneous file using the second argument as the name. + Install a miscellaneous file using the second argument as the name </ti> </tr> <tr> @@ -323,7 +391,7 @@ the first is the source name, the second the name to use when installing. <c>newlib.a</c> </ti> <ti> - Install a <c>.a</c> library file using the second argument as the name. + Install a <c>.a</c> library file using the second argument as the name </ti> </tr> <tr> @@ -331,7 +399,7 @@ the first is the source name, the second the name to use when installing. <c>newlib.so</c> </ti> <ti> - Install a <c>.so</c> library file using the second argument as the name. + Install a <c>.so</c> library file using the second argument as the name </ti> </tr> <tr> @@ -339,7 +407,7 @@ the first is the source name, the second the name to use when installing. <c>newman</c> </ti> <ti> - Install a manual page using the second argument as the name. + Install a manual page using the second argument as the name </ti> </tr> <tr> @@ -347,7 +415,28 @@ the first is the source name, the second the name to use when installing. <c>newsbin</c> </ti> <ti> - Install an <c>sbin</c> file using the second argument as the name. + Install an <c>sbin</c> file using the second argument as the name + </ti> + </tr> + <tr> + <ti> + <c>docompress</c> + </ti> + <ti> + Controls compression of files. Normally executed to exclude from + compression, e.g., <c>docompress -x /usr/share/doc/${PF}/examples</c>. + </ti> + </tr> + <tr> + <ti> + <c>dostrip</c> + </ti> + <ti> + Controls stripping of executables. Normally used to exclude from + stripping, e.g. <c>dostrip -x /usr/$(get_libdir)/important.so</c>. + May also be used without the <c>-x</c> option to include binaries to + strip when <c>RESTRICT=strip</c> is set. Provided paths are relative + to <c>${ED}</c>, even if they begin with a slash. </ti> </tr> </table> diff --git a/function-reference/message-functions/text.xml b/function-reference/message-functions/text.xml index 24f4b82..e5ea04f 100644 --- a/function-reference/message-functions/text.xml +++ b/function-reference/message-functions/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/message-functions/"> <chapter> <title>Message Functions Reference</title> @@ -74,52 +74,19 @@ displaying informational messages. Display the end of an action block. </ti> </tr> -</table> - -<p> - The following are available from <c>eutils.eclass</c> . ebeep and epause - are deprecated in EAPIS 0, 1 and 2 in favor of GLEP 42 news items and - package manager message logging functionality. -</p> - -<table> - <tr> - <th> - Function - </th> - <th> - Details - </th> - </tr> - <tr> - <ti> - <c>epause</c> - </ti> - <ti> - Pause for the specified number (must be a positive integer) of seconds. - Defaults to a sane value. - </ti> - </tr> - <tr> - <ti> - <c>ebeep</c> - </ti> - <ti> - Beep the specified number (must be a positive integer) of times. Defaults to a sane value. - </ti> - </tr> <tr> <ti> <c>eqawarn</c> </ti> <ti> Used by eclass authors to notify ebuild writers that they are using deprecated functionality. + Before EAPI=7, the eutils eclass must be inherited. </ti> </tr> </table> <p> -See <uri link="::ebuild-writing/messages"/> for a detailed discussion. +See <uri link="::ebuild-writing/messages/"/> for a detailed discussion. </p> </body> diff --git a/function-reference/query-functions/text.xml b/function-reference/query-functions/text.xml index dc88b9d..077e2cd 100644 --- a/function-reference/query-functions/text.xml +++ b/function-reference/query-functions/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/query-functions/"> <chapter> <title>Query Functions Reference</title> @@ -39,10 +39,22 @@ query variables and similar state. </tr> <tr> <ti> - <c>usev flagname</c> + <c>usev flagname [true output]</c> </ti> <ti> - As <c>use</c>, echoes <c>flagname</c> upon success. + As <c>use</c>, but also echoes <c>flagname</c> upon success. In EAPI 8 + and later, echoes the second argument instead, if it is specified. + </ti> + </tr> + <tr> + <ti> + <c>usex flag [true output] [false output] [true suffix] [false suffix]</c> + </ti> + <ti> + If <c>flag</c> is enabled, echo [true output][true suffix], otherwise + echo [false output][false suffix]. If unspecified, true and false outputs + are equal to "yes" and "no" respectively. The suffixes default to empty + strings. </ti> </tr> <tr> @@ -65,19 +77,26 @@ query variables and similar state. </tr> <tr> <ti> - <c>has flag string</c> + <c>in_iuse flag</c> </ti> <ti> - Returns true if <c>flag</c> is included in the flag list <c>string</c> - (example: <c>if has ccache $FEATURES ; then</c>). - The condition is inverted if prefixed with an exclamation mark, - <c>!flag</c>. + Returns true if the ebuild can use <c>flag</c> in <c>use</c> queries, + false otherwise. + </ti> + </tr> + <tr> + <ti> + <c>has word item...</c> + </ti> + <ti> + Returns true if <c>word</c> is found in the list of subsequent + <c>item</c> arguments (example: <c>if has ccache $FEATURES ; then</c>). It is guaranteed that <c>has</c> produces no output. </ti> </tr> <tr> <ti> - <c>hasq flag string</c> + <c>hasq word item...</c> </ti> <ti> Deprecated synonym for <c>has</c>. @@ -85,26 +104,41 @@ query variables and similar state. </tr> <tr> <ti> - <c>hasv flag string</c> + <c>hasv word item...</c> </ti> <ti> - As <c>has</c>, echoes <c>flag</c> on success. + As <c>has</c>, echoes <c>word</c> on success. </ti> </tr> <tr> <ti> - <c>best_version pkg</c> + <c>best_version [option] pkg</c> </ti> <ti> - Echoes the 'best' version of <c>pkg</c> which is currently installed. + Echoes category, name and version of the highest version of <c>pkg</c> + that is currently installed. + Example: <c>best_version app-editors/emacs:24</c> will output + <c>app-editors/emacs-24.5-r3</c>. + (EAPI=7) An option may also be specified to query certain types of dependencies. + <c>-b</c> for <c>BDEPEND</c> + <c>-d</c> for <c>DEPEND</c> + <c>-r</c> (default) for <c>RDEPEND</c> </ti> </tr> <tr> <ti> - <c>has_version pkg</c> + <c>has_version [option] pkg[flag]</c> </ti> <ti> - True if <c>pkg</c> (can include version specifiers) is installed. + True if <c>pkg</c> (can include + <uri link="::general-concepts/dependencies/#version specifiers"/> and + <uri link="::general-concepts/dependencies/#built with use dependencies"/>) + is installed. Example: <c>has_version + "=app-editors/nano-2.5.3[nls,spell]"</c>. + (EAPI=7) An option may also be specified to query certain types of dependencies. + <c>-b</c> for <c>BDEPEND</c> + <c>-d</c> for <c>DEPEND</c> + <c>-r</c> (default) for <c>RDEPEND</c> </ti> </tr> </table> diff --git a/function-reference/sandbox-functions/text.xml b/function-reference/sandbox-functions/text.xml index 4f355c5..ca5df54 100644 --- a/function-reference/sandbox-functions/text.xml +++ b/function-reference/sandbox-functions/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/sandbox-functions/"> <chapter> <title>Sandbox Functions Reference</title> @@ -61,9 +61,10 @@ recursive, so to allow predicted writes to <c>/foo/bar</c> and <c>/foo/baz</c>, </p> <p> -See <uri link="::general-concepts/sandbox"/> for details on how the sandbox works. -See <uri link="::appendices/common-problems/#Handling Access Violations"/> for how -to handle sandbox-related build problems. +See <uri link="::general-concepts/sandbox/"/> for details on how the sandbox +works. +See <uri link="::appendices/common-problems/#Handling Access Violations"/> +for how to handle sandbox-related build problems. </p> </body> diff --git a/function-reference/text.xml b/function-reference/text.xml index 336321d..a6ee821 100644 --- a/function-reference/text.xml +++ b/function-reference/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/"> <chapter> <title>Function Reference</title> @@ -18,6 +18,7 @@ The following functions are available for use in ebuilds: </chapter> <include href="build-functions/"/> +<include href="error-functions/"/> <include href="install-functions/"/> <include href="message-functions/"/> <include href="query-functions/"/> diff --git a/general-concepts/autotools/diagram.svg b/general-concepts/autotools/diagram.svg index 7e205e1..3ecea41 100644 --- a/general-concepts/autotools/diagram.svg +++ b/general-concepts/autotools/diagram.svg @@ -1,102 +1,410 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" - "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> -<svg viewBox="0 50 510 360" width="510" height="360" xmlns="http://www.w3.org/2000/svg" version="1.1"> - <desc>Autotools Build Process</desc> - <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" /> - - <rect x="0" y="70" width="470" height="122" - stroke-width="1" stroke="black" fill="none" - stroke-dasharray="5,5" rx="10" ry="10" /> - <text style="text-anchor: middle; font-style: italic;" - x="400" y="150">Usually handled</text> - <text style="text-anchor: middle; font-style: italic;" - x="400" y="164">by upstream</text> - - <rect x="130" y="197" width="330" height="63" - stroke-width="1" stroke="black" fill="none" - stroke-dasharray="5,5" rx="10" ry="10" /> - <text style="text-anchor: middle; font-style: italic;" - x="410" y="225">Shipped with</text> - <text style="text-anchor: middle; font-style: italic;" - x="410" y="239">the package</text> - - <rect x="10" y="150" width="80" height="30" - fill="#ccccff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="50" y="170">Makefile.am</text> - - <line x1="90" y1="165" x2="130" y2="165" stroke-width="2" stroke="black" /> - <line x1="130" y1="165" x2="122" y2="160" stroke-width="2" stroke="black" /> - <line x1="130" y1="165" x2="122" y2="170" stroke-width="2" stroke="black" /> - - <polygon points="130,165 180,145 230,165 180,185" fill="#ffffff" - stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="180" y="169">automake</text> - - <line x1="180" y1="185" x2="180" y2="215" stroke-width="2" stroke="black" /> - <line x1="185" y1="207" x2="180" y2="215" stroke-width="2" stroke="black" /> - <line x1="175" y1="207" x2="180" y2="215" stroke-width="2" stroke="black" /> - - <rect x="140" y="215" width="80" height="30" - fill="#ccffcc" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="180" y="235">Makefile.in</text> - - <line x1="220" y1="230" x2="260" y2="230" stroke-width="2" stroke="black" /> - <line x1="260" y1="230" x2="252" y2="235" stroke-width="2" stroke="black" /> - <line x1="260" y1="230" x2="252" y2="225" stroke-width="2" stroke="black" /> - - <polygon points="260,230 310,210 360,230 310,250" fill="#ccffcc" - stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="310" y="234">configure</text> - - <line x1="310" y1="115" x2="310" y2="210" stroke-width="2" stroke="black" /> - <line x1="315" y1="202" x2="310" y2="210" stroke-width="2" stroke="black" /> - <line x1="305" y1="202" x2="310" y2="210" stroke-width="2" stroke="black" /> - - <polygon points="260,95 310,75 360,95 310,115" fill="#ffffff" - stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="310" y="99">autoconf</text> - - - <line x1="220" y1="95" x2="260" y2="95" stroke-width="2" stroke="black" /> - <line x1="260" y1="95" x2="252" y2="90" stroke-width="2" stroke="black" /> - <line x1="260" y1="95" x2="252" y2="100" stroke-width="2" stroke="black" /> - - - <rect x="140" y="80" width="80" height="30" - fill="#ccccff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="180" y="93" >configure.in /</text> - <text style="text-anchor: middle;" x="180" y="105">configure.ac</text> - - <line x1="90" y1="165" x2="130" y2="165" stroke-width="2" stroke="black" /> - <line x1="130" y1="165" x2="122" y2="160" stroke-width="2" stroke="black" /> - <line x1="130" y1="165" x2="122" y2="170" stroke-width="2" stroke="black" /> - - <line x1="310" y1="250" x2="310" y2="285" stroke-width="2" stroke="black" /> - <line x1="315" y1="278" x2="310" y2="285" stroke-width="2" stroke="black" /> - <line x1="305" y1="278" x2="310" y2="285" stroke-width="2" stroke="black" /> - - <rect x="270" y="285" width="80" height="30" - fill="#ccffcc" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="310" y="305">Makefile</text> - - <line x1="350" y1="300" x2="390" y2="300" stroke-width="2" stroke="black" /> - <line x1="390" y1="300" x2="382" y2="295" stroke-width="2" stroke="black" /> - <line x1="390" y1="300" x2="382" y2="305" stroke-width="2" stroke="black" /> - - <polygon points="390,300 440,280 490,300 440,320" fill="#ffffff" - stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="440" y="304">make</text> - - <line x1="440" y1="320" x2="440" y2="355" stroke-width="2" stroke="black" /> - <line x1="435" y1="348" x2="440" y2="355" stroke-width="2" stroke="black" /> - <line x1="445" y1="348" x2="440" y2="355" stroke-width="2" stroke="black" /> - - <ellipse cx="440" cy="375" rx="50" ry="20" stroke-width="2" stroke="black" - fill="#ffcccc" /> - <text style="text-anchor: middle;" x="440" y="378">program</text> - +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + id="svg109" + version="1.1" + height="360" + width="510" + viewBox="0 50 510 360"> + <metadata + id="metadata115"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs113" /> + <desc + id="desc2">Autotools Build Process</desc> + <rect + id="background" + fill="#eeeeee" + height="1000" + width="1000" + y="-10" + x="-10" /> + <rect + id="rect5" + ry="10" + rx="10" + stroke-dasharray="5,5" + fill="none" + stroke="black" + stroke-width="1" + height="122" + width="470" + y="70" + x="0" /> + <text + id="text7" + y="150" + x="400" + style="text-anchor:middle;font-style:italic;-inkscape-font-specification:'Open Sans Italic';font-family:'Open Sans';font-weight:normal;font-stretch:normal;font-variant:normal;">Usually handled</text> + <text + id="text9" + y="164" + x="400" + style="text-anchor:middle;font-style:italic;-inkscape-font-specification:'Open Sans Italic';font-family:'Open Sans';font-weight:normal;font-stretch:normal;font-variant:normal;">by upstream</text> + <rect + id="rect11" + ry="10" + rx="10" + stroke-dasharray="5,5" + fill="none" + stroke="black" + stroke-width="1" + height="63" + width="330" + y="197" + x="130" /> + <text + id="text13" + y="225" + x="410" + style="text-anchor:middle;font-style:italic;-inkscape-font-specification:'Open Sans Italic';font-family:'Open Sans';font-weight:normal;font-stretch:normal;font-variant:normal;">Shipped with</text> + <text + id="text15" + y="239" + x="410" + style="text-anchor:middle;font-style:italic;-inkscape-font-specification:'Open Sans Italic';font-family:'Open Sans';font-weight:normal;font-stretch:normal;font-variant:normal;">the package</text> + <rect + id="rect17" + stroke-width="2" + stroke="black" + fill="#ccccff" + height="30" + width="80" + y="150" + x="10" /> + <text + id="text19" + y="170" + x="50" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Makefile.am</text> + <line + id="line21" + stroke="black" + stroke-width="2" + y2="165" + x2="130" + y1="165" + x1="90" /> + <line + id="line23" + stroke="black" + stroke-width="2" + y2="160" + x2="122" + y1="165" + x1="130" /> + <line + id="line25" + stroke="black" + stroke-width="2" + y2="170" + x2="122" + y1="165" + x1="130" /> + <polygon + id="polygon27" + stroke-width="2" + stroke="black" + fill="#ffffff" + points="130,165 180,145 230,165 180,185" /> + <text + id="text29" + y="169" + x="180" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">automake</text> + <line + id="line31" + stroke="black" + stroke-width="2" + y2="215" + x2="180" + y1="185" + x1="180" /> + <line + id="line33" + stroke="black" + stroke-width="2" + y2="215" + x2="180" + y1="207" + x1="185" /> + <line + id="line35" + stroke="black" + stroke-width="2" + y2="215" + x2="180" + y1="207" + x1="175" /> + <rect + id="rect37" + stroke-width="2" + stroke="black" + fill="#ccffcc" + height="30" + width="80" + y="215" + x="140" /> + <text + id="text39" + y="235" + x="180" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Makefile.in</text> + <line + id="line41" + stroke="black" + stroke-width="2" + y2="230" + x2="260" + y1="230" + x1="220" /> + <line + id="line43" + stroke="black" + stroke-width="2" + y2="235" + x2="252" + y1="230" + x1="260" /> + <line + id="line45" + stroke="black" + stroke-width="2" + y2="225" + x2="252" + y1="230" + x1="260" /> + <polygon + id="polygon47" + stroke-width="2" + stroke="black" + fill="#ccffcc" + points="260,230 310,210 360,230 310,250" /> + <text + id="text49" + y="234" + x="310" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">configure</text> + <line + id="line51" + stroke="black" + stroke-width="2" + y2="210" + x2="310" + y1="115" + x1="310" /> + <line + id="line53" + stroke="black" + stroke-width="2" + y2="210" + x2="310" + y1="202" + x1="315" /> + <line + id="line55" + stroke="black" + stroke-width="2" + y2="210" + x2="310" + y1="202" + x1="305" /> + <polygon + id="polygon57" + stroke-width="2" + stroke="black" + fill="#ffffff" + points="260,95 310,75 360,95 310,115" /> + <text + id="text59" + y="99" + x="310" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">autoconf</text> + <line + id="line61" + stroke="black" + stroke-width="2" + y2="95" + x2="260" + y1="95" + x1="220" /> + <line + id="line63" + stroke="black" + stroke-width="2" + y2="90" + x2="252" + y1="95" + x1="260" /> + <line + id="line65" + stroke="black" + stroke-width="2" + y2="100" + x2="252" + y1="95" + x1="260" /> + <rect + id="rect67" + stroke-width="2" + stroke="black" + fill="#ccccff" + height="30" + width="80" + y="80" + x="140" /> + <text + id="text71" + y="99" + x="180" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">configure.ac</text> + <line + id="line73" + stroke="black" + stroke-width="2" + y2="165" + x2="130" + y1="165" + x1="90" /> + <line + id="line75" + stroke="black" + stroke-width="2" + y2="160" + x2="122" + y1="165" + x1="130" /> + <line + id="line77" + stroke="black" + stroke-width="2" + y2="170" + x2="122" + y1="165" + x1="130" /> + <line + id="line79" + stroke="black" + stroke-width="2" + y2="285" + x2="310" + y1="250" + x1="310" /> + <line + id="line81" + stroke="black" + stroke-width="2" + y2="285" + x2="310" + y1="278" + x1="315" /> + <line + id="line83" + stroke="black" + stroke-width="2" + y2="285" + x2="310" + y1="278" + x1="305" /> + <rect + id="rect85" + stroke-width="2" + stroke="black" + fill="#ccffcc" + height="30" + width="80" + y="285" + x="270" /> + <text + id="text87" + y="305" + x="310" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Makefile</text> + <line + id="line89" + stroke="black" + stroke-width="2" + y2="300" + x2="390" + y1="300" + x1="350" /> + <line + id="line91" + stroke="black" + stroke-width="2" + y2="295" + x2="382" + y1="300" + x1="390" /> + <line + id="line93" + stroke="black" + stroke-width="2" + y2="305" + x2="382" + y1="300" + x1="390" /> + <polygon + id="polygon95" + stroke-width="2" + stroke="black" + fill="#ffffff" + points="390,300 440,280 490,300 440,320" /> + <text + id="text97" + y="304" + x="440" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">make</text> + <line + id="line99" + stroke="black" + stroke-width="2" + y2="355" + x2="440" + y1="320" + x1="440" /> + <line + id="line101" + stroke="black" + stroke-width="2" + y2="355" + x2="440" + y1="348" + x1="435" /> + <line + id="line103" + stroke="black" + stroke-width="2" + y2="355" + x2="440" + y1="348" + x1="445" /> + <ellipse + id="ellipse105" + fill="#ffcccc" + stroke="black" + stroke-width="2" + ry="20" + rx="50" + cy="375" + cx="440" /> + <text + id="text107" + y="378" + x="440" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">program</text> </svg> - -<!-- vim: set ft=xml sw=4 sts=4 et : --> - diff --git a/general-concepts/autotools/text.xml b/general-concepts/autotools/text.xml index 7ae2024..09162ff 100644 --- a/general-concepts/autotools/text.xml +++ b/general-concepts/autotools/text.xml @@ -1,12 +1,13 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/autotools/"> <chapter> <title>The Basics of Autotools</title> <body> <todo> -This is too long for <uri link="::general-concepts"/>. It needs to be split up and -moved somewhere, either to a top-level of its own or into <uri link="::appendices/"/>. +This is too long for <uri link="::general-concepts/"/>. It needs to be split up +and moved somewhere, either to a top-level of its own or into +<uri link="::appendices/"/>. </todo> <p> @@ -42,9 +43,9 @@ together with a few relatively simple upstream-supplied input files, are used to create the build system for a package. </p> -<figure short="How autotools fits together" link="diagram.png"> -A basic overview of how the main autotools components fit together. -</figure> +<figure short="How autotools fits together" link="diagram.png" + caption="A basic overview of how the main autotools components fit together." + /> <p> In a simple setup: @@ -76,20 +77,12 @@ and have the same format <d/> the only difference is the name. </note> <p> - You may see autotools being used in a variety of phase - functions. Prior to EAPI2, the QA team preferred that the source - code be manipulated in <c>src_unpack</c><d/>the rationale being that - <c>src_unpack</c> handles "getting the package ready to be - compiled." -</p> - -<p> - EAPI2, however, introduced a new phase function: <uri - link="::ebuild-writing/functions/src_prepare" />. This is now the - appropriate place to manipulate the source code prior to - configuration and compilation. In particular, <c>src_prepare</c> is - called before <uri link="::ebuild-writing/functions/src_configure" - />, which usually expects the <c>configure</c> script to exist. +You may see autotools being used in a variety of phase functions. +The <uri link="::ebuild-writing/functions/src_prepare/"/> function is the most +appropriate place to manipulate the source code prior to configuration +and compilation. In particular, <c>src_prepare</c> is called before +<uri link="::ebuild-writing/functions/src_configure/"/>, which usually expects +the <c>configure</c> script to exist. </p> <p> @@ -124,33 +117,31 @@ either <c>Makefile.am</c> or <c>configure.ac</c>: </p> <codesample lang="ebuild"> -EAPI="5" +EAPI=8 +WANT_AUTOCONF=2.5 +WANT_AUTOMAKE=1.9 inherit autotools +IUSE="nls" + +BDEPEND="nls? ( sys-devel/gettext )" + src_prepare() { - # Remove problematic LDFLAGS declaration - sed -i -e '/^LDFLAGS/d' src/Makefile.am || die + default + + # Remove problematic LDFLAGS declaration + sed -i -e '/^LDFLAGS/d' src/Makefile.am || die - # Rerun autotools - einfo "Regenerating autotools files..." - WANT_AUTOCONF=2.5 eautoconf - WANT_AUTOMAKE=1.9 eautomake + # Rerun autotools + eautoreconf } -src_compile() { - econf $(use_enable nls) - emake +src_configure() { + econf $(use_enable nls) } </codesample> -<p> -The <c>einfo</c> message before running autotools is not mandatory. However, these -steps can sometimes take a while and may produce no output, so it may make sense -to let the user know that something is still happening. See -<uri link="::ebuild-writing/messages"/>. -</p> - </body> </section> @@ -487,7 +478,7 @@ man_MANS = glep31check.1 EXTRA_DIST = glep31check.in %.1 : %.in - @regex_cmd@ -e "s,\@VERSION\@,$(VERSION),g" $? > $@ + @regex_cmd@ -e "s,\@VERSION\@,$(VERSION),g" $? > $@ </codesample> <p> @@ -505,10 +496,10 @@ This is handled via the macro <c>AC_SUBST(VARNAME)</c> in <c>configure.ac</c>. <p> Sometimes, badly behaved <c>Makefile.am</c> files will override user variables such as <c>CFLAGS</c>. This must not be allowed <d/> see -<uri link="::general-concepts/user-environment#Not Filtering Variables"/>. There -are separate special variables which should be used in these situations <d/> for -setting <c>CFLAGS</c>. for example, a <c>Makefile.am</c> should use <c>AM_CFLAGS</c> so -that user preferences are not ignored. +<uri link="::general-concepts/user-environment/#Not Filtering Variables"/>. +There are separate special variables which should be used in these situations +<d/> for setting <c>CFLAGS</c>. for example, a <c>Makefile.am</c> should use +<c>AM_CFLAGS</c> so that user preferences are not ignored. </p> <p> @@ -599,10 +590,17 @@ In the first case you usually want to do something like: </p> <codesample lang="ebuild"> -einfo "Regenerating autotools files..." -cp "${WORKDIR}/gentoo-m4" "${S}/m4" || die "m4 copy failed" -WANT_AUTOCONF="2.5" aclocal -I "${S}/m4" || die "aclocal failed" -WANT_AUTOCONF="2.5" autoconf || die "autoconf failed" +WANT_AUTOCONF="2.5" +inherit autotools + +src_prepare() { + default + + einfo "Regenerating autotools files..." + cp "${WORKDIR}/gentoo-m4" "${S}/m4" || die "m4 copy failed" + eaclocal -I "${S}/m4" + eautoconf +} </codesample> <p> @@ -610,9 +608,16 @@ and so on. In the second case you can simplify it in this way: </p> <codesample lang="ebuild"> -einfo "Regenerating autotools files..." -WANT_AUTOCONF="2.5" aclocal -I "${WORKDIR}/gentoo-m4" || die "aclocal failed" -WANT_AUTOCONF="2.5" autoconf || die "autoconf failed" +WANT_AUTOCONF="2.5" +inherit autotools + +src_prepare() { + default + + einfo "Regenerating autotools files..." + eaclocal -I "${WORKDIR}/gentoo-m4" + eautoconf +} </codesample> <p> @@ -653,32 +658,35 @@ For more details on autotools: The book "GNU Autoconf, Automake and Libtool" by Gary V. Vaughan, Ben Elliston, Tom Tromey and Ian Lance Taylor (often called "The Autobook") provides a good but somewhat outdated description of autotools. It is - <uri link="http://sources.redhat.com/autobook/">freely available online</uri>. + <uri link="https://sourceware.org/autobook/">freely available online</uri>. </li> <li> The GNU documentation for the various autotools components is of varying quality and completeness: - </li> - <ul> + <ul> <li> - <uri link="http://www.gnu.org/software/automake/manual/automake.html"> + <uri link="https://www.gnu.org/software/automake/manual/automake.html"> GNU automake Manual </uri> </li> <li> - <uri link="http://www.gnu.org/software/autoconf/manual/">GNU autoconf Manual</uri> + <uri link="https://www.gnu.org/software/autoconf/manual/">GNU autoconf Manual</uri> </li> <li> - <uri link="http://www.gnu.org/software/libtool/manual/">GNU libtool Manual</uri> + <uri link="https://www.gnu.org/software/libtool/manual/">GNU libtool Manual</uri> </li> <li> - <uri link="http://www.gnu.org/software/m4/manual/m4.html">GNU m4 Manual</uri> + <uri link="https://www.gnu.org/software/m4/manual/m4.html">GNU m4 Manual</uri> </li> - </ul> + <li> + <uri link="https://autotools.io">Autotools Mythbuster</uri> + </li> + </ul> + </li> <li> - There are some good overview lectures available online. <uri - link="http://www.shlomifish.org/lecture/Autotools/">These - slides</uri> are one example. + There are some good overview lectures available online. + <uri link="https://www.shlomifish.org/lecture/Autotools/">These slides</uri> + are one example. </li> </ul> diff --git a/general-concepts/config-protect/text.xml b/general-concepts/config-protect/text.xml index ec74a86..acbb89d 100644 --- a/general-concepts/config-protect/text.xml +++ b/general-concepts/config-protect/text.xml @@ -1,30 +1,46 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/config-protect/"> <chapter> <title>Configuration File Protection</title> - <body> + <p> - Portage includes a system for configuration file protection which means ebuilds - don't have to worry about accidentally clobbering files in <c>/etc</c>. This is - known as 'protection', and it is controlled by the <c>CONFIG_PROTECT</c> and - <c>CONFIG_PROTECT_MASK</c> variables. +Portage includes a system for configuration file protection which means ebuilds +don't have to worry about accidentally clobbering files in <c>/etc</c>. This is +known as 'protection', and it is controlled by the <c>CONFIG_PROTECT</c> and +<c>CONFIG_PROTECT_MASK</c> variables. </p> <p> - Any directory which is listed in <c>CONFIG_PROTECT</c> (and any subdirectories - thereof), except for any which are listed in <c>CONFIG_PROTECT_MASK</c> (and - subdirectories) are automatically 'protected' by Portage when copying an image - from <c>DESTDIR</c> to <c>ROOT</c>. Rather than installing protected files directly, - Portage will install them as <c>._cfg0000_filename</c>. These can then be processed - by the <c>etc-update</c> or <c>dispatch-conf</c> files at the user's discretion. +Any directory which is listed in <c>CONFIG_PROTECT</c> (and any subdirectories +thereof), except for any which are listed in <c>CONFIG_PROTECT_MASK</c> (and +subdirectories) are automatically 'protected' by Portage when copying an image +from <c>DESTDIR</c> to <c>ROOT</c>. Rather than installing protected files +directly, Portage will install them as <c>._cfg0000_filename</c>. These can +then be processed by the <c>etc-update</c> or <c>dispatch-conf</c> files at +the user's discretion. </p> <p> - Packages must <b>not</b> attempt to override this system via <c>pkg_postinst</c> or - similar. If you need a file renamed, removed or changed in a particular way, you - should display a message informing the user. +Packages must <b>not</b> attempt to override this system via <c>pkg_postinst</c> +or similar. If you need a file renamed, removed or changed in a particular way, +you should display a message informing the user. </p> + +<p> +An ebuild can append to the <c>CONFIG_PROTECT_MASK</c> variable by using +Portage's <uri link="::tasks-reference/environment/"/> mechanism. The ebuild +has to generate an <c>env.d</c> file, then install it using <c>doenvd</c> or +<c>newenvd</c>. <c>emerge</c> shall call <c>env-update</c> and generate the +proper environment for proceeding with its merge. The following snippet (from +<c>src_install</c>) shall cause <c>/etc/test.cfg</c> to be auto-merged without +needing to call <c>etc-update</c> after the package is merged: +</p> + +<codesample lang="ebuild"> + newenvd - 99my-pkg <<< "CONFIG_PROTECT_MASK=\"/etc/test.cfg\"" +</codesample> + </body> </chapter> </guide> diff --git a/general-concepts/copyright-policy/diagram.dot b/general-concepts/copyright-policy/diagram.dot new file mode 100644 index 0000000..5b29ab7 --- /dev/null +++ b/general-concepts/copyright-policy/diagram.dot @@ -0,0 +1,43 @@ +// Copyright 2023 Gentoo Authors +// Distributed under the terms of the CC-BY-SA-4.0 license + +digraph g { + size = "8!,2"; + node [ penwidth = 2; fontname = "Open Sans" ]; + edge [ penwidth = 2; fontname = "Open Sans" ]; + + start [ width = 1.4; height = 0.9; label = "Start" ]; + + signoff [ shape = diamond; width = 2.4; height = 1.3; + style = filled; fillcolor = "cyan"; + label = "Signed-off-by?" ]; + size [ shape = diamond; width = 2.4; height = 1.3; + style = filled; fillcolor = "cyan"; + label = "Tiny\ncontribution?" ]; + license [ shape = diamond; width = 2.4; height = 1.3; + style = filled; fillcolor = "cyan"; + label = "Contains\nlicense notice?" ]; + + accept4 [ shape = rect; width = 1.6; height = 0.8; + style = filled; fillcolor = "lime"; + label = "Accept\n(GCO point 4)" ]; + accept2 [ shape = rect; width = 1.6; height = 0.8; + style = filled; fillcolor = "lime"; + label = "Accept\n(GCO point 2)" ]; + reject [ shape = rect; width = 1.6; height = 0.7; + style = filled; fillcolor = "red"; + label = "Do not accept" ]; + + start -> signoff; + + signoff:s -> accept4 [ label = " Yes " ]; + signoff -> size [ label = " No " ]; + + size:s -> accept2 [ label = " Yes " ]; + size -> license [ label = " No " ]; + + license:s -> accept2 [ label = " Yes " ]; + license -> reject [ label = " No " ]; + + { rank = same; start; signoff; size; license; reject; } +} diff --git a/general-concepts/copyright-policy/diagram.svg b/general-concepts/copyright-policy/diagram.svg new file mode 100644 index 0000000..3affb30 --- /dev/null +++ b/general-concepts/copyright-policy/diagram.svg @@ -0,0 +1,107 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<!-- Generated by graphviz version 9.0.0 (20230911.1827) + --> +<!-- Title: g Pages: 1 --> +<svg width="576pt" height="132pt" + viewBox="0.00 0.00 576.00 131.70" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph0" class="graph" transform="scale(0.613419 0.613419) rotate(0) translate(4 210.7)"> +<title>g</title> +<polygon fill="white" stroke="none" points="-4,4 -4,-210.7 935,-210.7 935,4 -4,4"/> +<!-- start --> +<g id="node1" class="node"> +<title>start</title> +<ellipse fill="none" stroke="black" stroke-width="2" cx="50.4" cy="-159.9" rx="50.4" ry="32.4"/> +<text text-anchor="middle" x="50.4" y="-156.35" font-family="Open Sans" font-size="14.00">Start</text> +</g> +<!-- signoff --> +<g id="node2" class="node"> +<title>signoff</title> +<polygon fill="cyan" stroke="black" stroke-width="2" points="222.4,-206.7 136,-159.9 222.4,-113.1 308.8,-159.9 222.4,-206.7"/> +<text text-anchor="middle" x="222.4" y="-156.35" font-family="Open Sans" font-size="14.00">Signed-off-by?</text> +</g> +<!-- start->signoff --> +<g id="edge1" class="edge"> +<title>start->signoff</title> +<path fill="none" stroke="black" stroke-width="2" d="M101.8,-159.9C108.32,-159.9 114.83,-159.9 121.35,-159.9"/> +<polygon fill="black" stroke="black" stroke-width="2" points="121.28,-163.4 131.28,-159.9 121.28,-156.4 121.28,-163.4"/> +</g> +<!-- size --> +<g id="node3" class="node"> +<title>size</title> +<polygon fill="cyan" stroke="black" stroke-width="2" points="446.4,-206.7 360,-159.9 446.4,-113.1 532.8,-159.9 446.4,-206.7"/> +<text text-anchor="middle" x="446.4" y="-166.1" font-family="Open Sans" font-size="14.00">Tiny</text> +<text text-anchor="middle" x="446.4" y="-146.6" font-family="Open Sans" font-size="14.00">contribution?</text> +</g> +<!-- signoff->size --> +<g id="edge3" class="edge"> +<title>signoff->size</title> +<path fill="none" stroke="black" stroke-width="2" d="M310.61,-159.9C321.91,-159.9 333.54,-159.9 345.03,-159.9"/> +<polygon fill="black" stroke="black" stroke-width="2" points="344.88,-163.4 354.88,-159.9 344.88,-156.4 344.88,-163.4"/> +<text text-anchor="middle" x="334.4" y="-169.1" font-family="Open Sans" font-size="14.00">  No  </text> +</g> +<!-- accept4 --> +<g id="node5" class="node"> +<title>accept4</title> +<polygon fill="lime" stroke="black" stroke-width="2" points="280,-57.6 164.8,-57.6 164.8,0 280,0 280,-57.6"/> +<text text-anchor="middle" x="222.4" y="-35" font-family="Open Sans" font-size="14.00">Accept</text> +<text text-anchor="middle" x="222.4" y="-15.5" font-family="Open Sans" font-size="14.00">(GCO point 4)</text> +</g> +<!-- signoff->accept4 --> +<g id="edge2" class="edge"> +<title>signoff:s->accept4</title> +<path fill="none" stroke="black" stroke-width="2" d="M222.4,-113.1C222.4,-99.43 222.4,-84.51 222.4,-71.11"/> +<polygon fill="black" stroke="black" stroke-width="2" points="225.9,-71.36 222.4,-61.36 218.9,-71.36 225.9,-71.36"/> +<text text-anchor="middle" x="240.77" y="-81.8" font-family="Open Sans" font-size="14.00">  Yes  </text> +</g> +<!-- license --> +<g id="node4" class="node"> +<title>license</title> +<polygon fill="cyan" stroke="black" stroke-width="2" points="674.4,-206.7 584.66,-159.9 674.4,-113.1 764.14,-159.9 674.4,-206.7"/> +<text text-anchor="middle" x="674.4" y="-166.1" font-family="Open Sans" font-size="14.00">Contains</text> +<text text-anchor="middle" x="674.4" y="-146.6" font-family="Open Sans" font-size="14.00">license notice?</text> +</g> +<!-- size->license --> +<g id="edge5" class="edge"> +<title>size->license</title> +<path fill="none" stroke="black" stroke-width="2" d="M534.88,-159.9C546.25,-159.9 557.97,-159.9 569.57,-159.9"/> +<polygon fill="black" stroke="black" stroke-width="2" points="569.56,-163.4 579.56,-159.9 569.56,-156.4 569.56,-163.4"/> +<text text-anchor="middle" x="558.73" y="-169.1" font-family="Open Sans" font-size="14.00">  No  </text> +</g> +<!-- accept2 --> +<g id="node6" class="node"> +<title>accept2</title> +<polygon fill="lime" stroke="black" stroke-width="2" points="618,-57.6 502.8,-57.6 502.8,0 618,0 618,-57.6"/> +<text text-anchor="middle" x="560.4" y="-35" font-family="Open Sans" font-size="14.00">Accept</text> +<text text-anchor="middle" x="560.4" y="-15.5" font-family="Open Sans" font-size="14.00">(GCO point 2)</text> +</g> +<!-- size->accept2 --> +<g id="edge4" class="edge"> +<title>size:s->accept2</title> +<path fill="none" stroke="black" stroke-width="2" d="M446.4,-113.1C446.4,-86.44 466.98,-67.39 490.65,-54.31"/> +<polygon fill="black" stroke="black" stroke-width="2" points="492.02,-57.54 499.36,-49.9 488.86,-51.29 492.02,-57.54"/> +<text text-anchor="middle" x="479.77" y="-81.8" font-family="Open Sans" font-size="14.00">  Yes  </text> +</g> +<!-- license->accept2 --> +<g id="edge6" class="edge"> +<title>license:s->accept2</title> +<path fill="none" stroke="black" stroke-width="2" d="M674.4,-113.1C674.4,-86.44 653.82,-67.39 630.15,-54.31"/> +<polygon fill="black" stroke="black" stroke-width="2" points="631.94,-51.29 621.44,-49.9 628.78,-57.54 631.94,-51.29"/> +<text text-anchor="middle" x="687.77" y="-81.8" font-family="Open Sans" font-size="14.00">  Yes  </text> +</g> +<!-- reject --> +<g id="node7" class="node"> +<title>reject</title> +<polygon fill="red" stroke="black" stroke-width="2" points="931,-185.1 815.8,-185.1 815.8,-134.7 931,-134.7 931,-185.1"/> +<text text-anchor="middle" x="873.4" y="-156.35" font-family="Open Sans" font-size="14.00">Do not accept</text> +</g> +<!-- license->reject --> +<g id="edge7" class="edge"> +<title>license->reject</title> +<path fill="none" stroke="black" stroke-width="2" d="M766.04,-159.9C778.12,-159.9 790.35,-159.9 802.03,-159.9"/> +<polygon fill="black" stroke="black" stroke-width="2" points="801.9,-163.4 811.9,-159.9 801.9,-156.4 801.9,-163.4"/> +<text text-anchor="middle" x="789.97" y="-169.1" font-family="Open Sans" font-size="14.00">  No  </text> +</g> +</g> +</svg> diff --git a/general-concepts/copyright-policy/text.xml b/general-concepts/copyright-policy/text.xml new file mode 100644 index 0000000..c8d6865 --- /dev/null +++ b/general-concepts/copyright-policy/text.xml @@ -0,0 +1,147 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="general-concepts/copyright-policy/"> +<chapter> +<title>Copyright Policy</title> +<body> + +<p> +<uri link="https://www.gentoo.org/glep/glep-0076.html">GLEP 76</uri> defines +copyright and license policies for Gentoo Linux. +</p> + +<p> +Every Gentoo project must abide by the +<uri link="https://www.gentoo.org/get-started/philosophy/social-contract.html"> +Gentoo Social Contract</uri> and release its work under one or more of the +following licenses: +</p> + +<ul> + <li> + The <uri link="https://www.gnu.org/licenses/gpl-2.0.html"> + GNU General Public License, version 2 or later</uri> (GPL-2+) + </li> + <li> + The <uri link="https://creativecommons.org/licenses/by-sa/4.0/"> + Creative Commons Attribution-ShareAlike 4.0 International License</uri> + (CC-BY-SA-4.0), only for documentation + </li> + <li> + Any + <uri link="https://www.gnu.org/licenses/license-list.en.html#GPLCompatibleLicenses"> + GPL-compatible free software license</uri> + </li> +</ul> + +<p> +Exceptions for other (GPL-incompatible) free software licenses may be granted +by the Gentoo Foundation on a case-by-case basis. +</p> + +</body> + +<section> +<title>Certificate of Origin</title> +<body> + +<p> +Per GLEP 76, you must sign-off all your commits to any Gentoo-hosted repository +with accordance to the +<uri link="https://www.gentoo.org/glep/glep-0076.html#certificate-of-origin"> +copyright policy</uri>. +</p> + +<p> +When committing work authored by someone else, e.g. a Bugzilla patch, or GitHub +pull request, a sign-off from the original author is always strongly +recommended, in order to indicate that the author acknowledges Gentoo's +copyright policy. However, it is not mandatory for every case. Please refer to +the example list below when determining whether a sign-off from the original +author is, or is not required. The list below serves as a general guideline. +</p> +</body> + +<subsection> +<title>General guideline</title> +<body> + +<figure link="diagram.png" short="When can a contribution be accepted?" + caption="Flowchart showing the steps for accepting a contribution" /> + +<p> +When can a contribution be accepted? +</p> + +<ol type="1"> + <li> + <p> + When signed off by its author (i.e. with a <c>Signed-off-by</c> line): + </p> + <p> + Can be accepted, because the author has confirmed that it is under a free + software license. The committer adds another <c>Signed-off-by</c> line and + certifies the commit under point 4 of the + <uri link="https://www.gentoo.org/glep/glep-0076.html#certificate-of-origin"> + Certificate of Origin</uri>. + </p> + <note> + Use common sense here, especially if you don't know the contributor. + If the contribution was taken from somewhere else and the contributor + doesn't have the right to distribute it under a free software license, + you as the committer might get into trouble. So in this situation, do your + best to check repositories for matching code, and whether they hold any + special copyright claims. + </note> + </li> + <li> + <p> + When <e>not</e> signed off: + </p> + <ol type="a"> + <li> + <p> + If the contribution is not of + <uri link="https://www.gnu.org/prep/maintain/html_node/Legally-Significant.html"> + "legally significant"</uri> size (by the FSF's 15-lines rule of thumb): + </p> + <p> + Can be accepted. The committer adds a <c>Signed-off-by</c> line and + certifies the commit under point 2 of the Certificate of Origin. + </p> + </li> + <li> + <p> + If the contribution is of significant size, and + </p> + <ol type="i"> + <li> + <p> + with an independent indication of its license (e.g. copyright and + license notices in the file's header): + </p> + <p> + Can be accepted. The committer adds a <c>Signed-off-by</c> line and + certifies the commit under point 2 of the Certificate of Origin. + </p> + </li> + <li> + <p> + <e>without</e> any other indication of its license: + </p> + <p> + Can <e>not</e> be accepted. There's no indication that the author + has released their work under a free license, therefore it must not + be distributed by Gentoo. + </p> + </li> + </ol> + </li> + </ol> + </li> +</ol> +</body> +</subsection> + +</section> +</chapter> +</guide> diff --git a/general-concepts/cvs-to-rsync/diagram.svg b/general-concepts/cvs-to-rsync/diagram.svg deleted file mode 100644 index ed31af7..0000000 --- a/general-concepts/cvs-to-rsync/diagram.svg +++ /dev/null @@ -1,142 +0,0 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" - "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> -<svg width="700" height="250" xmlns="http://www.w3.org/2000/svg" version="1.1"> - <desc>CVS to RSYNC Propagation</desc> - - <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" /> - - <rect x="10" y="110" width="80" height="30" - fill="#ffcccc" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="50" y="130">Developers</text> - - <line x1="90" y1="125" x2="130" y2="125" stroke-width="2" stroke="black" /> - <line x1="130" y1="125" x2="122" y2="120" stroke-width="2" stroke="black" /> - <line x1="130" y1="125" x2="122" y2="130" stroke-width="2" stroke="black" /> - - - <rect x="10" y="60" width="80" height="30" - fill="#ffcccc" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="50" y="80">Developers</text> - - <path d="M 90 75 Q 110 75 110 100 Q 110 130 130 125" - stroke-width="2" stroke="black" fill="none" /> - - <rect x="10" y="160" width="80" height="30" - fill="#ffcccc" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="50" y="180">Developers</text> - - <path d="M 90 175 Q 110 175 110 150 Q 110 120 130 125" - stroke-width="2" stroke="black" fill="none" /> - - <rect x="130" y="110" width="80" height="30" - fill="#ffffff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="170" y="130">CVS</text> - - <line x1="210" y1="125" x2="250" y2="125" stroke-width="2" stroke="black" /> - <line x1="250" y1="125" x2="242" y2="120" stroke-width="2" stroke="black" /> - <line x1="250" y1="125" x2="242" y2="130" stroke-width="2" stroke="black" /> - - - - <rect x="250" y="110" width="80" height="30" - fill="#ffffff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="290" y="123">Staging</text> - <text style="text-anchor: middle;" x="290" y="135">Box</text> - - <line x1="330" y1="125" x2="370" y2="125" stroke-width="2" stroke="black" /> - <line x1="370" y1="125" x2="362" y2="120" stroke-width="2" stroke="black" /> - <line x1="370" y1="125" x2="362" y2="130" stroke-width="2" stroke="black" /> - - - - <rect x="370" y="110" width="80" height="30" - fill="#ffffff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="410" y="130">rsync1</text> - - - - <line x1="490" y1="75" x2="482" y2="70" stroke-width="2" stroke="black" /> - <line x1="490" y1="75" x2="482" y2="80" stroke-width="2" stroke="black" /> - <path d="M 450 125 Q 470 125 470 100 Q 470 70 490 75" - stroke-width="2" stroke="black" fill="none" /> - - <rect x="490" y="60" width="80" height="30" - fill="#ccffcc" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="530" y="80">Public rsync</text> - - - - <line x1="450" y1="125" x2="490" y2="125" stroke-width="2" stroke="black" /> - <line x1="490" y1="125" x2="482" y2="120" stroke-width="2" stroke="black" /> - <line x1="490" y1="125" x2="482" y2="130" stroke-width="2" stroke="black" /> - - <rect x="490" y="110" width="80" height="30" - fill="#ccffcc" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="530" y="130">Public rsync</text> - - - - <line x1="490" y1="175" x2="482" y2="170" stroke-width="2" stroke="black" /> - <line x1="490" y1="175" x2="482" y2="180" stroke-width="2" stroke="black" /> - <path d="M 450 125 Q 470 125 470 150 Q 470 180 490 175" - stroke-width="2" stroke="black" fill="none" /> - - <rect x="490" y="160" width="80" height="30" - fill="#ccffcc" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="530" y="180">Public rsync</text> - - - - <line x1="610" y1="25" x2="602" y2="20" stroke-width="2" stroke="black" /> - <line x1="610" y1="25" x2="602" y2="30" stroke-width="2" stroke="black" /> - <path d="M 570 75 Q 590 75 590 50 Q 590 20 610 25" - stroke-width="2" stroke="black" fill="none" /> - - <rect x="610" y="10" width="80" height="30" - fill="#ccccff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="650" y="30">Users</text> - - - - <line x1="570" y1="75" x2="610" y2="75" stroke-width="2" stroke="black" /> - <line x1="610" y1="75" x2="602" y2="70" stroke-width="2" stroke="black" /> - <line x1="610" y1="75" x2="602" y2="80" stroke-width="2" stroke="black" /> - - <rect x="610" y="60" width="80" height="30" - fill="#ccccff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="650" y="80">Users</text> - - - - <line x1="570" y1="125" x2="610" y2="125" stroke-width="2" stroke="black" /> - <line x1="610" y1="125" x2="602" y2="120" stroke-width="2" stroke="black" /> - <line x1="610" y1="125" x2="602" y2="130" stroke-width="2" stroke="black" /> - - <rect x="610" y="110" width="80" height="30" - fill="#ccccff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="650" y="130">Users</text> - - - <line x1="570" y1="175" x2="610" y2="175" stroke-width="2" stroke="black" /> - <line x1="610" y1="175" x2="602" y2="170" stroke-width="2" stroke="black" /> - <line x1="610" y1="175" x2="602" y2="180" stroke-width="2" stroke="black" /> - - <rect x="610" y="160" width="80" height="30" - fill="#ccccff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="650" y="180">Users</text> - - - - <line x1="610" y1="225" x2="602" y2="220" stroke-width="2" stroke="black" /> - <line x1="610" y1="225" x2="602" y2="230" stroke-width="2" stroke="black" /> - <path d="M 570 175 Q 590 175 590 200 Q 590 230 610 225" - stroke-width="2" stroke="black" fill="none" /> - - <rect x="610" y="210" width="80" height="30" - fill="#ccccff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="650" y="230">Users</text> - -</svg> - -<!-- vim: set ft=xml sw=4 sts=4 et : --> diff --git a/general-concepts/cvs-to-rsync/text.xml b/general-concepts/cvs-to-rsync/text.xml deleted file mode 100644 index 9a379e6..0000000 --- a/general-concepts/cvs-to-rsync/text.xml +++ /dev/null @@ -1,40 +0,0 @@ -<?xml version="1.0"?> -<guide self="general-concepts/cvs-to-rsync/"> -<chapter> -<title>CVS to RSYNC</title> - -<body> - -<p> - Changes made to the tree are propagated to the users in stages: -</p> - -<ul> - <li> - Developer commits to CVS. - </li> - <li> - Staging box syncs from CVS and generates the metadata cache. - </li> - <li> - <c>rsync1</c> syncs from the staging box. - </li> - <li> - Public rsync servers sync from <c>rsync1</c>. - </li> - <li> - Users sync from the public rsync servers. - </li> -</ul> - -<figure short="CVS to RSYNC Propagation" link="diagram.png"> - Diagram showing CVS to RSYNC Propagation -</figure> - -<p> - The <c>emerge-websync</c> snapshot is made daily from the staging box. -</p> - -</body> -</chapter> -</guide> diff --git a/general-concepts/dependencies/text.xml b/general-concepts/dependencies/text.xml index 24b9902..98a84d1 100644 --- a/general-concepts/dependencies/text.xml +++ b/general-concepts/dependencies/text.xml @@ -1,40 +1,106 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/dependencies/"> <chapter> <title>Dependencies</title> - <body> <p> - Automatic dependency resolution is one of the most useful features provided by - <c>emerge</c>. +Automatic dependency resolution is one of the most useful features +provided by <c>emerge</c>. +</p> + +<p> +You are encouraged to sort dependencies alphabetically, with unconditional +dependencies grouped together, then all conditional dependencies. There is an +exception: you may sort dependencies as per upstream listings if it eases +checking for changes. Some projects may have different policies <d/> consult +them if you're not sure. +</p> + +<p> +Please also see the following section on +<uri link="::general-concepts/ebuild-revisions/"/> +for how dependencies and revisions interact. </p> +</body> + <section> +<title>Dependency types</title> + +<subsection> +<title>CHOST vs CBUILD</title> +<body> + +<p> +In order to avoid ambiguity, we use the following terms to indicate different +systems when cross-compiling. They serve as a shorthand for an overall system +in addition to their literal value (e.g. $CHOST). +</p> + +<dl> + <dt>CBUILD</dt> + <dd> + The system on which the build is performed. Dependencies that apply + to the CBUILD system can be executed during build time. + </dd> + + <dt>CHOST</dt> + <dd> + The system on which the package is going to be executed. When + cross-compiling, dependencies applying to CHOST can not be executed. + </dd> +</dl> + +<p> +When cross-compiling, CBUILD and CHOST are naturally different, as are the +actual install paths for the different types of dependencies. +</p> + +<p> +Note however that, while cross-compiling is used to help explain these concepts, +it is not strictly required. CBUILD and CHOST could target the exact same +hardware, but be installed into distinct SYSROOT/ROOT paths. The dependency +distinctions still apply even if it isn't, strictly speaking, cross-compiling. +</p> + +</body> +</subsection> + +<subsection> <title>Build Dependencies</title> <body> <p> -The <c>DEPEND</c> ebuild variable should specify any dependencies which are -required to unpack, patch, compile or install the package (but see -<uri link="::general-concepts/dependencies#Implicit System Dependency"/> for +Build dependencies are used to specify any dependencies that are required +to unpack, patch, compile, test or install the package (but see +<uri link="::general-concepts/dependencies/#Implicit System Dependency"/> for exemptions). </p> +<p> +Starting with EAPI 7, build dependencies are split into two variables: +<c>BDEPEND</c> and <c>DEPEND</c>. <c>BDEPEND</c> specifies dependencies +applicable to CBUILD, i.e. programs that need to be executed during the build, +e.g. <c>virtual/pkgconfig</c>. <c>DEPEND</c> specifies dependencies for CHOST, +i.e. packages that need to be found on built system, e.g. libraries and headers. +</p> + +<p> +In earlier EAPIs, all build dependencies are placed in <c>DEPEND</c>. +</p> + </body> -</section> +</subsection> -<section> +<subsection> <title>Runtime Dependencies</title> <body> <p> The <c>RDEPEND</c> ebuild variable should specify any dependencies which are required at runtime. This includes libraries (when dynamically linked), any data -packages and (for interpreted languages) the relevant interpreter. In EAPI=3 or -older, if this variable is not specified it defaults to the value of -<c>DEPEND</c>, however the implicit usage is frowned upon. In EAPI=4, the -implicit behaviour was removed and the assignment is always explicit. +packages and (for interpreted languages) the relevant interpreter. </p> <p> @@ -49,52 +115,27 @@ Items which are in <c>RDEPEND</c> but not <c>DEPEND</c> could <e>in theory</e> b </p> </body> -</section> +</subsection> -<section> -<title>Post-Merge Dependencies</title> +<subsection> +<title>Post Dependencies</title> <body> <p> -The <c>PDEPEND</c> variable specifies dependencies that should be -merged <e>after</e> the package, but which may be merged at any time, -if the former is not possible. This is sometimes used for plugins -that have a dependency upon the package being merged. Generally -<c>PDEPEND</c> should be avoided in favour of <c>RDEPEND</c> except -where this will create circular dependency chains. +The <c>PDEPEND</c> variable specifies runtime dependencies that do not strictly +require being satisfied immediately. They can be merged <e>after</e> +the package. This variable is used purely to resolve circular dependencies, +while in general case <c>RDEPEND</c> should be used instead. </p> </body> +</subsection> </section> <section> -<title>Implicit System Dependency</title> -<body> - -<p> -All packages have an implicit compile-time and runtime dependency upon the -entire <c>system</c> target. It is therefore not necessary, nor advisable, to -specify dependencies upon toolchain packages like <c>gcc</c>, <c>libc</c> and -so on, except where specific versions or packages (for example, <c>glibc</c> -over <c>uclibc</c>) are required. Note that this rule also needs consideration -for packages like <c>flex</c>, <c>zlib</c> and <c>libtool</c>, which aren't in -the <c>system</c> target for every profile. For example, the embedded profile -doesn't have <c>zlib</c> in <c>system</c> target, the <c>libtool</c> ABI might -change and break building order and <c>flex</c> might get removed from the -<c>system</c> target in future. -</p> - -<p> -However, packages which are included in the <c>system</c> target, or are -dependencies of <c>system</c> target packages, should generally include a complete -dependency list (excluding bootstrap packages). This makes <c>emerge -e system</c> -possible when installing from a stage 1 or stage 2 tarball. -</p> - -</body> -</section> +<title>Dependency Syntax</title> -<section> +<subsection> <title>Basic Dependency Syntax</title> <body> @@ -104,21 +145,21 @@ A basic <c>DEPEND</c> specification might look like the following: <codesample lang="ebuild"> DEPEND="dev-lang/ruby - dev-ruby/ruby-gtk2 - dev-ruby/mysql-ruby" + dev-ruby/ruby-gtk2 + dev-ruby/mysql-ruby" </codesample> <p> -Each atom is the full category and name of a package. Atoms are separated by -arbitrary whitespace <d/> convention is to specify one atom per line for -readability purposes. When specifying names, the category part should be treated -as mandatory. +Each <e>package dependency specification</e> is the full category and name of +a package. Dependency specifications are separated by arbitrary whitespace <d/> +convention is to have one specification per line for readability purposes. +When specifying names, the category part should be treated as mandatory. </p> </body> -</section> +</subsection> -<section> +<subsection> <title>Version Dependencies</title> <body> @@ -128,14 +169,15 @@ should be specified. A simple example: </p> <codesample lang="ebuild"> -DEPEND=">=dev-libs/openssl-0.9.7d" +DEPEND=">=dev-libs/openssl-0.9.7d" </codesample> <p> This states that at least version 0.9.7d of <c>openssl</c> is required. </p> +</body> -<subsection> +<subsubsection> <title>Version Specifiers</title> <body> @@ -143,18 +185,17 @@ This states that at least version 0.9.7d of <c>openssl</c> is required. Available version specifiers are: </p> -<p> <table> <tr> <th>Specifier</th> <th>Meaning</th> </tr> <tr> - <ti><c>>=app-misc/foo-1.23</c></ti> + <ti><c>>=app-misc/foo-1.23</c></ti> <ti>Version 1.23 or later is required.</ti> </tr> <tr> - <ti><c>>app-misc/foo-1.23</c></ti> + <ti><c>>app-misc/foo-1.23</c></ti> <ti>A version strictly later than 1.23 is required.</ti> </tr> <tr> @@ -177,12 +218,11 @@ Available version specifiers are: <ti>A version strictly before 1.23 is required.</ti> </tr> </table> -</p> </body> -</subsection> +</subsubsection> -<subsection> +<subsubsection> <title>Ranged Dependencies</title> <body> @@ -192,7 +232,7 @@ the asterisk postfix. This is most commonly seen in situations like: </p> <codesample lang="ebuild"> -DEPEND="gtk? ( =x11-libs/gtk+-1.2* )" +DEPEND="gtk? ( =x11-libs/gtk+-2* )" </codesample> <p> @@ -202,15 +242,25 @@ asterisk. Also note that when selecting all versions in a specific </p> </body> -</subsection> +</subsubsection> -<subsection> +<subsubsection> <title>Blockers</title> <body> <p> -Sometimes two packages cannot be installed in parallel. This is handled by -blockers. A softblocker is specified as follows: +When two packages (package slots, versions) can not be installed +simultaneously, blockers can be used to expose such a conflict +to the package manager. +</p> + +<p> +There are two kinds of blockers: <e>weak blockers</e> and <e>strong +blockers</e>. +</p> + +<p> +A weak blocker is defined using the following syntax: </p> <codesample lang="ebuild"> @@ -218,10 +268,35 @@ RDEPEND="!app-misc/foo" </codesample> <p> -Portage will try to resolve this conflict automatically if possible. -Sometimes we need to use a hardblocker to ensure correct emerge order. -Those cannot be resolved by Portage and must be taken care of by the user. -A hardblocker is specified as follows: +The package manager will try to resolve this conflict automatically. +The package blocked by a weak blocker can be uninstalled <e>after</e> +installing the package blocking it. However, it exempts the common +files from file collision checks. Weak blockers are usually used +to solve file collisions between packages and are meaningful only +in <c>RDEPEND</c>. +</p> + +<p> +More specifically, installation of the newer package may overwrite any +colliding files that belong to the older package that is explicitly blocked. +When such file collisions occur, the colliding files cease to belong to the +older package, and they remain installed after the older package is eventually +uninstalled. The older package is uninstalled only after any newer blocking +packages have been merged on top of it. +</p> + +<warning> +Weak blockers that are pure <c>DEPEND</c> <e>do not work correctly</e>. +While Portage seemingly queues the package for removal, it <e>does not</e> +exempt their contents from file collision checks. Always include your +weak blockers in <c>RDEPEND</c>! +</warning> + +<p> +If it is strictly necessary to resolve the blocker before the package +is built (installed), a strong blocker must be used instead. In this case, +temporary simultaneous installation of the conflicting packages is not allowed. +Strong blockers are expressed using the following syntax: </p> <codesample lang="ebuild"> @@ -229,10 +304,25 @@ RDEPEND="!!app-misc/foo" </codesample> <p> -Hardblockers always take precedence over softblockers and need at least EAPI="2". -Also note that blockers are usually <e>runtime</e> rather than buildtime. +Strong blockers apply accordingly to the dependency type defining them. +Blockers defined in <c>RDEPEND</c> are enforced as long as the package +is installed (but do not prevent building binary packages). Blockers +defined purely in <c>DEPEND</c> are enforced only for building +the package from source, and may not apply once the package is installed +or when it is installed from a binary package. +</p> + +<p> +The most common use for strong blockers is where another package simply +being installed causes a build failure. Strong blockers are not to be used +to prevent just file collisions. </p> +<note> +If both weak and strong blockers match a given package, the strong blocker +takes precedence. +</note> + <p> Specific versions can also be blocked: </p> @@ -251,34 +341,27 @@ Blockers added to older ebuilds should not be expected to be retroactive. If the user already has the ebuild installed, any changes to the ebuild should not be expected to make any difference. This means that you should add the blockers to whichever ebuild is the newest (even if it means that logically it -would seem backwards). For example, certain versions of portage don't like +would seem backwards). For example, certain versions of Portage don't like some versions of bash, but the blocker was put into bash because that was the newer package that caused the issues. </p> </body> +</subsubsection> </subsection> -</body> -</section> - -<section> +<subsection> <title>SLOT Dependencies</title> <body> <p> -In order to depend on a package in a specific <c>SLOT</c> you must specify -at least <c>EAPI="1"</c>. -</p> - -<p> To depend on a specific <c>SLOT</c>, <c>:SLOT</c> should be appended to the package name, where 'SLOT' is the <c>SLOT</c> of the package wanted: </p> <codesample lang="ebuild"> -DEPEND="qt3? ( x11-libs/qt:3 ) - gtk? ( x11-libs/gtk+:2 ) +DEPEND="qt5? ( dev-qt/qtcore:5 ) + gtk? ( x11-libs/gtk+:2 ) </codesample> <p> @@ -286,35 +369,47 @@ To depend on a specific version or version-range within a SLOT we use: </p> <codesample lang="ebuild"> -DEPEND="qt3? ( ~x11-libs/qt-3.3.8:3 ) - gtk? ( >=x11-libs/gtk+-2.24.9:2 ) +DEPEND="qt5? ( ~dev-qt/qtcore-5.15.2:5 ) + gtk? ( >=x11-libs/gtk+-2.24.9:2 ) </codesample> +</body> -<subsection> +<subsubsection> <title>Slot Operators</title> <body> <p> -In <c>EAPI="5"</c> and higher, you can use slot operators appended to the package +In <c>EAPI=5</c> and higher, you can use slot operators appended to the package name to declare whether or not your package should be rebuilt after the versions satisfying its runtime dependencies are updated to versions with a different slot -or <uri link="::general-concepts/slotting#Sub-Slots">sub-slot</uri>: +or <uri link="::general-concepts/slotting/#Sub-Slots">sub-slot</uri>: </p> <ul> - <li><c>:=</c> means that any slot is acceptable, and that your package should be - rebuilt if the version best matching the runtime dependency is updated to a - version with a different slot or subslot;</li> - <li><c>:*</c> means that any slot is acceptable, and explicitly declares that - changes in the slot or sub-slot can be ignored;</li> - <li><c>:SLOT=</c> means that only the 'SLOT' slot is acceptable, and that your - package should be rebuilt if the version matching the runtime dependency is - updated to another version with this slot but with a different subslot;</li> - <li><c>:SLOT</c> means that only the 'SLOT' slot is acceptable, and that changes - in the sub-slot can be ignored (like in previous EAPIs).</li> - <li><c>:SLOT/SUBSLOT</c> means a dependency on a specific slot and sub-slot pair, - which can be useful for packages installing pre-built binaries that require a - library with a particular soname version corresponding to the sub-slot.</li> + <li> + <c>:=</c> means that any slot is acceptable. Additionally indicates that + your package should be rebuilt if the version best matching the runtime + dependency is updated to a version with a different slot or subslot. + </li> + <li> + <c>:*</c> means that any slot is acceptable. Furthermore, this slot + operator explicitly declares that changes in the slot or sub-slot can be + ignored. + </li> + <li> + <c>:SLOT=</c> means that only the 'SLOT' slot is acceptable. It otherwise + behaves identically to the <c>:=</c> operator. That is, the package must be + rebuilt if the sub-slot of the dependency changes. + </li> + <li> + <c>:SLOT</c> means that only the 'SLOT' slot is acceptable, and that changes + in the sub-slot can be ignored (like in previous EAPIs). + </li> + <li> + <c>:SLOT/SUBSLOT</c> means a dependency on a specific slot and sub-slot pair, + which can be useful for packages installing pre-built binaries that require a + library with a particular soname version corresponding to the sub-slot. + </li> </ul> <p> @@ -323,16 +418,46 @@ For example: <codesample lang="ebuild"> RDEPEND="media-libs/cogl:1.0= - gnutls? ( >=net-libs/gnutls-2.8:= )" + gnutls? ( >=net-libs/gnutls-2.8:= )" </codesample> -</body> -</subsection> +<p> +means that only the '1.0' slot is acceptable for <c>media-libs/cogl</c> and +that sub-slot changes of <c>media-libs/cogl</c> will cause a rebuild of the +dependent package. It furthermore means that every slot of +<c>net-libs/gnutls</c> is acceptable but any slot change is causing a rebuild. +</p> + +<p> +The <c>:slot</c> dependency syntax continues to behave like in <c>EAPI=4</c> or +earlier, i.e. it indicates that only the specific slot value is acceptable and +that the package will not break when the currently installed version of the +dependency is replaced by a version with a different sub-slot. +</p> + +<p> +For example: +</p> + +<codesample lang="ebuild"> +RDEPEND="dev-libs/foo:2= + >=dev-libs/bar-0.9:= + media-gfx/baz:* + x11-misc/wombat:0" +</codesample> + +<p> +means that the package should be rebuilt when <c>foo:2</c> or +<c>>=bar-0.9</c> are upgraded to versions with different subslots. On the +other hand, changes in slot or sub-slots of <c>baz</c> should be ignored, and +sub-slot changes of <c>wombat:0</c> should be ignored. +</p> </body> -</section> +</subsubsection> +</subsection> -<section> +<subsection> <title>USE-Conditional Dependencies</title> <body> @@ -342,8 +467,8 @@ To depend upon a certain package if and only if a given <c>USE</c> flag is set: <codesample lang="ebuild"> DEPEND="perl? ( dev-lang/perl ) - ruby? ( >=dev-lang/ruby-1.8 ) - python? ( dev-lang/python )" + ruby? ( >=dev-lang/ruby-1.8 ) + python? ( dev-lang/python )" </codesample> <p> @@ -359,7 +484,7 @@ RDEPEND="!crypt? ( net-misc/netkit-rsh )" This should <b>not</b> be used for disabling a certain <c>USE</c> flag on a given architecture. In order to do this, the architecture team should add the <c>USE</c> flag to their <c>use.mask</c> file in the <c>profiles/arch</c> -directory of the Portage tree. +directory of the Gentoo repository. </p> <p> @@ -368,32 +493,36 @@ This can be nested: <codesample lang="ebuild"> DEPEND="!build? ( - gcj? ( - gtk? ( - x11-libs/libXt - x11-libs/libX11 - x11-libs/libXtst - x11-proto/xproto - x11-proto/xextproto - >=x11-libs/gtk+-2.2 - x11-libs/pango - ) - >=media-libs/libart_lgpl-2.1 - ) - >=sys-libs/ncurses-5.2-r2 - nls? ( sys-devel/gettext ) + >=sys-libs/ncurses-5.2-r2 + gcj? ( + >=media-libs/libart_lgpl-2.1 + gtk? ( + x11-libs/libXt + x11-libs/libX11 + x11-libs/libXtst + x11-proto/xproto + x11-proto/xextproto + >=x11-libs/gtk+-2.2 + x11-libs/pango + ) + ) + nls? ( sys-devel/gettext ) )" </codesample> </body> -</section> +</subsection> -<section> -<title> -Any of Many Dependencies -</title> +<subsection> +<title>Any of Many Dependencies</title> <body> +<note> +To ease dependency resolution for Portage, it is recommended that you sort +the elements in <e>preferred</e> order first. See +<uri link="https://bugs.gentoo.org/489458">this bug</uri> for more context. +</note> + <p> To depend on either <c>foo</c> or <c>bar</c>: </p> @@ -409,8 +538,9 @@ To depend on either <c>foo</c> or <c>bar</c> if the <c>baz</c> <c>USE</c> flag i <codesample lang="ebuild"> DEPEND="baz? ( || ( app-misc/foo app-misc/bar ) )" </codesample> +</body> -<subsection> +<subsubsection> <title>Any of Many Versus USE</title> <body> @@ -432,20 +562,14 @@ flag is not necessary if and only if all of the following hold: </ul> </body> +</subsubsection> </subsection> -</body> -</section> - -<section> +<subsection> <title>Built with USE Dependencies</title> <body> <p> -In order to use built with use dependencies you must specify <c>EAPI="2"</c>. -</p> - -<p> Available specifiers are: </p> @@ -494,57 +618,227 @@ There are also shortcuts for conditional situations: <ti><c>bar? ( app-misc/foo[-bar] ) !bar? ( app-misc/foo[bar] )</c></ti> </tr> </table> +</body> -<subsection> +<subsubsection> <title>Use dependency defaults</title> <body> <p> -If a dependency is introducing or removing a <c>USE</c> flag in new versions, a use -dependency default may be used. Appending a <c>(+)</c> or <c>(-)</c> suffix will indicate -whether the absence of the flag from a particular version should indicate its -presence or absence. +If a dependency is introducing or removing a <c>USE</c> flag in a new package +version, a <c>(+)</c> or <c>(-)</c> may be added to the use-dependency +specification to define a default value in case the flag does not exist in the +target package. The <c>(+)</c> indicates that the missing flag is assumed to be +enabled, <c>(-)</c> the opposite. </p> + <p> -<c>>=dev-libs/boost-1.48[threads(+)]</c> will treat all versions without <c>threads</c> as having it set. +For example, the following will treat all <c>boost</c> versions without the +<c>threads</c> flag as having it enabled, and all <c>gcc</c> versions without +the <c>openmp</c> as having it disabled: </p> +<codesample lang="ebuild"> +DEPEND=" + >=dev-libs/boost-1.48[threads(+)] + sys-devel/gcc[openmp(-)]" +</codesample> + </body> +</subsubsection> </subsection> +</section> + +<section> +<title>Tips for Checking Dependencies</title> +<body> + +<p> +It is important to ensure that all the dependencies are complete for your +package: +</p> + +<dl> + <dt>Look at installed binaries/libraries</dt> + <dd> + Use a tool like <c>scanelf -n</c> (from app-misc/pax-utils) or + <c>objdump -p</c> (from sys-devel/binutils) to list <c>DT_NEEDED</c> + entries. + app-portage/iwdevtools and portage's own <c>qa-unresolved-soname-deps</c> + <b>FEATURE</b> can help finding these. + </dd> + <dt>Look in <c>configure.ac</c></dt> + <dd> + Look for checks for packages in here. Things to look out for are pkg-config + checks or <c>AM_*</c> functions that check for a specific version. + </dd> + <dt>Look at included <c>.spec</c> files</dt> + <dd> + A good indication of dependencies is to look at the included <c>.spec</c> + files for relevant deps. However, do not trust them to be the definitive + complete list of dependencies. + </dd> + <dt>Look at the application/library website</dt> + <dd> + Check the application website for possible dependencies that they suggest + are needed. + </dd> + <dt>Read the <c>README</c> and <c>INSTALL</c> for the package</dt> + <dd> + They usually also contain useful information about building and installing + packages. + </dd> + <dt> + Remember non-binary dependencies such as pkg-config, doc generation + programs, etc. Such programs would usually belong in <c>BDEPEND</c>. + </dt> + <dd> + Usually the build process requires some dependencies such as intltool, + libtool, pkg-config, doxygen, scrollkeeper, gtk-doc, etc. Make sure those + are clearly stated. Again, such dependencies usually belong in + <c>BDEPEND</c>. + </dd> + <dt>Testing in chroots, containers and virtual machines</dt> + <dd> + A sure-way to find missing dependencies is to test your ebuild in a + deprived environment. Chroots, containers, virtual machines and + <c>dev-util/ebuildtester</c> can achieve this. + </dd> +</dl> </body> </section> <section> -<title>Legacy Inverse USE-Conditional Dependency Syntax</title> +<title>Implicit System Dependency</title> <body> <p> - Once upon a time the <c>:</c> conditional operator was allowed in <c>*DEPEND</c>: +All packages have an implicit compile-time and runtime dependency upon the +entire <c>@system</c> set. It is therefore not necessary, nor advisable, to +specify dependencies upon toolchain packages like <c>gcc</c>, <c>libc</c> and +so on, except where specific versions or packages (for example, <c>glibc</c> +over <c>uclibc</c>) are required. Note that this rule also needs consideration +for packages like <c>flex</c>, <c>zlib</c> and <c>libtool</c>, which aren't in +the <c>@system</c> set for every profile. For example, the embedded profile +doesn't have <c>zlib</c> in <c>@system</c>, the <c>libtool</c> ABI might +change and break building order and <c>flex</c> might get removed from the +<c>@system</c> set in future. </p> -<codesample lang="ebuild"> -DEPEND="use-flag? ( app-misc/foo ) : ( app-misc/bar )" -</codesample> +<p> +However, packages which are included in the <c>@system</c> set, or are +dependencies of <c>@system</c> set packages, should generally include +a complete dependency list (excluding bootstrap packages). This makes +<c>emerge -e @system</c> possible when installing from a stage 1 or stage 2 +tarball. +</p> + +</body> +</section> + +<section> +<title>Test Dependencies</title> +<body> <p> -<b>This syntax is no longer permitted</b>. It is exactly equivalent to the -following, which should be used instead: +Packages often have optional dependencies that are needed only when running +tests. These should be specified in DEPEND behind a USE flag. Often, the +'test' USE flag is used for this purpose. +</p> + +<p> +Since testing will likely fail when test dependencies are not installed, the +test phase should be disabled in this case. This may be accomplished via USE +conditionals in the RESTRICT variable. +</p> + +<p> +If other optional features must be enabled/disabled when testing, REQUIRED_USE +may be set to express this. </p> <codesample lang="ebuild"> -DEPEND="use-flag? ( app-misc/foo ) - !use-flag? ( app-misc/bar )" +# Define some USE flags +IUSE="debug test" + +# Require debug support when tests are enabled +REQUIRED_USE="test? ( debug )" + +# Disable test phase when test USE flag is disabled +RESTRICT="!test? ( test )" + +# Running tests requires 'foo' to be installed +DEPEND="test? ( dev-util/foo )" </codesample> +</body> +</section> + +<section> +<title>Circular Dependencies</title> +<body> + <p> -It is useful to recognise the legacy syntax and to know that it is no longer -valid. +Circular dependencies occur if one or more of package's (possibly indirect) +dependencies depend on the package itself. This creates a dependency cycle where +each of the packages must technically be installed before the other. +For example, if package A depends on B, B depends on C and C depends on A, then +the package manager cannot install A before C, and C before A. </p> +<p> +There are three kinds of circular dependencies: +</p> + +<ol> + <li> + Circular dependencies that occur if only one of the packages strictly needs + to be installed before the other. For example, <c>dev-python/certifi</c> + strictly requires <c>dev-python/setuptools</c> to build but the latter + package requires the former for some runtime functionality. As a result, + <c>dev-python/certifi</c> can be installed later than the other package. + <c>PDEPEND</c> is used to express this and automatically resolve + the circular dependency. + </li> + + <li> + Circular dependencies that occur if the cycle applies only to some + combination of USE flags on one of the packages. For example, running tests + in <c>dev-python/setuptools</c> requires a number of packages which require + <c>dev-python/setuptools</c> to be installed first. This kind of circular + dependency can be resolved by the user by adjusting USE flags on one + of the packages, e.g. by disabling tests on <c>dev-python/setuptools</c>, + and reenabling them once the dependency is initially installed. + </li> + + <li> + Circular dependencies that cannot be resolved using the regular means. + For example, <c>dev-util/cmake</c> used to depend + on <c>dev-libs/jsoncpp</c>, while the latter package used the former + to build. Resolving this kind of dependency usually requires bundling one + of the dependencies conditionally, or providing an alternate bootstrap path. + </li> +</ol> + </body> </section> +<section> +<title>Indirect dependencies</title> +<body> + +<p> +Always list each direct dependency that your package needs to build and run +correctly. Do not rely on dependency chains to meet the dependency +requirements. For example, a package needs <c>dep1</c> and <c>dep2</c>, but +<c>dep1</c> also depends on <c>dep2</c>. You might consider just adding +<c>dep1</c> since it currently pulls <c>dep2</c> too, but in the future, +<c>dep1</c> might drop <c>dep2</c> as a dependency, or make it conditional with +USE flags. This would then break building your ebuild. +</p> + </body> +</section> </chapter> </guide> diff --git a/general-concepts/distributed-building/text.xml b/general-concepts/distributed-building/text.xml deleted file mode 100644 index 003c27f..0000000 --- a/general-concepts/distributed-building/text.xml +++ /dev/null @@ -1,13 +0,0 @@ -<?xml version="1.0"?> -<guide self="general-concepts/distributed-building/"> -<chapter> -<title>Distributed and Parallel Building</title> - -<body> - -<todo>Write this.</todo> - -</body> -</chapter> -</guide> - diff --git a/general-concepts/ebuild-revisions/text.xml b/general-concepts/ebuild-revisions/text.xml index 9ddc39f..8248a6e 100644 --- a/general-concepts/ebuild-revisions/text.xml +++ b/general-concepts/ebuild-revisions/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/ebuild-revisions/"> <chapter> <title>Ebuild Revisions</title> @@ -6,35 +6,124 @@ <body> <p> Ebuilds may have a Gentoo revision number associated with them. This is a -<c>-rX</c> suffix, where <c>X</c> is an integer <d/> see <uri -link="::ebuild-writing/file-format#File Naming Rules"/>. This -component must only be used for Gentoo changes, not upstream releases. By -default, <c>-r0</c> is implied. +<c>-rX</c> suffix, where <c>X</c> is an integer <d/> see +<uri link="::ebuild-writing/file-format/#File Naming Rules"/>. +This component must only be used for Gentoo changes, not upstream releases. +An ebuild with no explicit revision number has the implicit <c>-r0</c> +revision. </p> -<p> -Ebuilds should have their <c>-rX</c> incremented whenever a change is made which -will make a substantial difference to what gets installed by the package <d/> by -substantial, we generally mean "something for which many users would want to -upgrade". This is usually for bugfixes. -</p> +<p>Ebuild revisions usually serve two purposes:</p> +<ol> + <li> + keeping an older copy of an ebuild around when doing a potentially + breaking change, and + </li> + + <li> + propagating the rebuild of a package when performing a meaningful + change that would otherwise go unnoticed by users who have installed + the current version already. + </li> +</ol> <p> -Simple compile fixes do <b>not</b> warrant a revision bump; this is because they do -not affect the installed package for users who already managed to compile it. -Small documentation fixes are also usually not grounds for a new revision. +Developers are encouraged to use common sense when determining +whether to introduce a new <c>-rX</c> revision. The following rule +of thumb could be used as a guideline: </p> +<ol> + <li> + If the change can cause the package to be broken to the point + of requiring users to revert to the previous version (in the case + of packages marked stable, every non-trivial change is classified + as such), then a new revision should be introduced and the old one + kept. If the package has stable keywords, the new revision should + be dropped to <c>~arch</c> (see + <uri link="::keywording/#Keywording on Upgrades"/>). + For any such revision bump, the new ebuild should be based + on the previous revision to ensure that fixes aren't dropped + accidentally. + </li> -<important> -For ebuilds marked stable on at least one arch, only trivial edits can be made -without a bump (e.g. typo fixes in elog messages). Even simple changes may -result in a breakage. <b>Modifying stable ebuilds should be avoided.</b> -</important> + <li> + If the change makes a substantial difference to the user who already + installed the package (fixes runtime issues, changes installed files, + etc.) and it would not be propagated using other means, then + the ebuild should be renamed to a new revision. If the package has + stable keywords, they should be moved to the new revision without + dropping. To commit the ebuild, <c>pkgdev commit</c> or <c>git + commit</c> paired with <c>pkgcheck scan --commits</c> should be used). + </li> -<p> -When doing a revision bump, the usual rules about dropping to <c>~arch</c> apply. -See <uri link="::keywording#Keywording on Upgrades"/>. -</p> + <li> + Otherwise, the change can be done in place in the current revision + of the ebuild. + </li> +</ol> + +<p>Examples of changes that warrant a new revision are:</p> +<ul> + <li>adding a patch to fix a runtime issue,</li> + <li>installing additional files that could be useful to the user,</li> + <li>adding a missing runtime dependency to one of the existing blocks,</li> + <li>adding a binding subslot operator (:=) to a dependency,</li> + <li>updating a dependency with default on/off USE flags,</li> + <li>fixing an automagic dependency detection from a build system,</li> + <li> + restricting a runtime dependency version, unless the <c>:=</c> + subslot operator is going to trigger a rebuild, + </li> + <li> + updating the license, if any of the affected licenses is either non-free or + is about to be removed, + </li> + <li> + changing the EAPI (unless changes to the ebuild are trivial, and you can be + sure it won't break stable or reverse dependencies). + </li> +</ul> + +<p>Examples of changes that can be done without a revision bump are:</p> +<ul> + <li> + adding a patch to fix a build-time issue that prevented users from + building the package (since it does not affect users who already + managed to build it) unless: it affected runtime behaviour in some way + (e.g. <c>-Wformat</c> or <c>-Wimplicit-function-declaration</c> fixes); + the package may have been miscompiled, or the change is substantial + (if adding a huge patch to fix a problem, the chances of an unexpected + issue being introduced by it are greater). + </li> + <li>adding a trivial documentation fix,</li> + <li> + installing an additional file of relatively little value (minor + documentation, editor syntax file, bash completion) compared + to the cost of rebuilding the package (especially if a new bump + is expected soon), + </li> + <li> + adding a missing build-time dependency that caused a build failure + (unless it is also a runtime dependency), + </li> + <li> + adding a new USE flag if it controls a USE-dependency where the + functionality was hard-disabled in the build system before, + </li> + <li> + removing an existing USE flag if it controls a USE-dependency where the + functionality is now disabled entirely, rather than always being enabled + (since the change in USE flags is going to trigger a <c>--changed-use</c> + rebuild), + </li> + <li> + a trivial stylistic / ebuild code change (as long as the new code + is equivalent to the old code), + </li> + <li> + a dependency change that is a result of a package move (slot move), + </li> +</ul> </body> </chapter> diff --git a/general-concepts/emerge-and-ebuild/diagram.svg b/general-concepts/emerge-and-ebuild/diagram.svg index 2e28cb2..42f77ed 100644 --- a/general-concepts/emerge-and-ebuild/diagram.svg +++ b/general-concepts/emerge-and-ebuild/diagram.svg @@ -1,55 +1,241 @@ -<?xml version="1.0" standalone="no"?> -<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" - "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> -<svg viewBox="0 100 500 220" width="500" height="220" xmlns="http://www.w3.org/2000/svg" version="1.1"> - <desc>Emerge and Ebuild</desc> - <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" /> - - <rect x="50" y="150" width="100" height="30" - fill="#ccffcc" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="100" y="170"># emerge foo</text> - - <line x1="150" y1="165" x2="200" y2="165" stroke-width="2" stroke="black" /> - <line x1="200" y1="165" x2="193" y2="160" stroke-width="2" stroke="black" /> - <line x1="200" y1="165" x2="193" y2="170" stroke-width="2" stroke="black" /> - - <rect x="200" y="150" width="100" height="30" - fill="#ffffff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="250" y="170">emerge</text> - - <line x1="220" y1="180" x2="220" y2="250" stroke-width="2" stroke="black" /> - <line x1="220" y1="250" x2="215" y2="243" stroke-width="2" stroke="black" /> - <line x1="220" y1="250" x2="225" y2="243" stroke-width="2" stroke="black" /> - <text style="text-anchor: end;" x="210" y="220">$PN, phases</text> - - <line x1="280" y1="180" x2="280" y2="250" stroke-width="2" stroke="black" /> - <line x1="280" y1="180" x2="275" y2="187" stroke-width="2" stroke="black" /> - <line x1="280" y1="180" x2="285" y2="187" stroke-width="2" stroke="black" /> - <text style="text-anchor: start;" x="290" y="220">Image in $D</text> - - <rect x="200" y="250" width="100" height="30" - fill="#ffffff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="250" y="270">ebuild.sh</text> - - <rect x="50" y="250" width="100" height="30" - fill="#ccccff" stroke="black" stroke-width="2" /> - <text style="text-anchor: middle;" x="100" y="270">foo-1.23.ebuild</text> - - <line x1="150" y1="265" x2="200" y2="265" stroke-width="2" stroke="black" /> - <line x1="200" y1="265" x2="193" y2="260" stroke-width="2" stroke="black" /> - <line x1="200" y1="265" x2="193" y2="270" stroke-width="2" stroke="black" /> - - <line x1="300" y1="165" x2="350" y2="165" stroke-width="2" stroke="black" /> - <line x1="350" y1="165" x2="343" y2="160" stroke-width="2" stroke="black" /> - <line x1="350" y1="165" x2="343" y2="170" stroke-width="2" stroke="black" /> - - <ellipse cx="400" cy="165" rx="50" ry="20" stroke-width="2" stroke="black" - fill="#ffcccc" /> - <text style="text-anchor: middle;" x="400" y="164">Installed image</text> - <text style="text-anchor: middle;" x="400" y="177">in $ROOT</text> - +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + id="svg61" + version="1.1" + height="220" + width="500" + viewBox="0 100 500 220"> + <metadata + id="metadata67"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs65" /> + <desc + id="desc2">Emerge and Ebuild</desc> + <rect + id="background" + fill="#eeeeee" + height="1000" + width="1000" + y="-10" + x="-10" /> + <rect + id="rect5" + stroke-width="2" + stroke="black" + fill="#ccffcc" + height="30" + width="100" + y="150" + x="50" /> + <text + id="text7" + y="170" + x="100" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;"># emerge foo</text> + <line + id="line9" + stroke="black" + stroke-width="2" + y2="165" + x2="200" + y1="165" + x1="150" /> + <line + id="line11" + stroke="black" + stroke-width="2" + y2="160" + x2="193" + y1="165" + x1="200" /> + <line + id="line13" + stroke="black" + stroke-width="2" + y2="170" + x2="193" + y1="165" + x1="200" /> + <rect + id="rect15" + stroke-width="2" + stroke="black" + fill="#ffffff" + height="30" + width="100" + y="150" + x="200" /> + <text + id="text17" + y="170" + x="250" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">emerge</text> + <line + id="line19" + stroke="black" + stroke-width="2" + y2="250" + x2="220" + y1="180" + x1="220" /> + <line + id="line21" + stroke="black" + stroke-width="2" + y2="243" + x2="215" + y1="250" + x1="220" /> + <line + id="line23" + stroke="black" + stroke-width="2" + y2="243" + x2="225" + y1="250" + x1="220" /> + <text + id="text25" + y="220" + x="210" + style="text-anchor:end;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">$PN, phases</text> + <line + id="line27" + stroke="black" + stroke-width="2" + y2="250" + x2="280" + y1="180" + x1="280" /> + <line + id="line29" + stroke="black" + stroke-width="2" + y2="187" + x2="275" + y1="180" + x1="280" /> + <line + id="line31" + stroke="black" + stroke-width="2" + y2="187" + x2="285" + y1="180" + x1="280" /> + <text + id="text33" + y="220" + x="290" + style="text-anchor:start;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Image in $D</text> + <rect + id="rect35" + stroke-width="2" + stroke="black" + fill="#ffffff" + height="30" + width="100" + y="250" + x="200" /> + <text + id="text37" + y="270" + x="250" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">ebuild.sh</text> + <rect + id="rect39" + stroke-width="2" + stroke="black" + fill="#ccccff" + height="30" + width="100" + y="250" + x="50" /> + <text + id="text41" + y="270" + x="100" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">foo-1.23.ebuild</text> + <line + id="line43" + stroke="black" + stroke-width="2" + y2="265" + x2="200" + y1="265" + x1="150" /> + <line + id="line45" + stroke="black" + stroke-width="2" + y2="260" + x2="193" + y1="265" + x1="200" /> + <line + id="line47" + stroke="black" + stroke-width="2" + y2="270" + x2="193" + y1="265" + x1="200" /> + <line + id="line49" + stroke="black" + stroke-width="2" + y2="165" + x2="350" + y1="165" + x1="300" /> + <line + id="line51" + stroke="black" + stroke-width="2" + y2="160" + x2="343" + y1="165" + x1="350" /> + <line + id="line53" + stroke="black" + stroke-width="2" + y2="170" + x2="343" + y1="165" + x1="350" /> + <ellipse + id="ellipse55" + fill="#ffcccc" + stroke="black" + stroke-width="2" + ry="20" + rx="50" + cy="165" + cx="400" /> + <text + id="text57" + y="164" + x="400" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Installed image</text> + <text + id="text59" + y="177" + x="400" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">in $ROOT</text> </svg> - -<!-- vim: set ft=xml sw=4 sts=4 et : --> - - diff --git a/general-concepts/emerge-and-ebuild/text.xml b/general-concepts/emerge-and-ebuild/text.xml index 16bc056..19e1a84 100644 --- a/general-concepts/emerge-and-ebuild/text.xml +++ b/general-concepts/emerge-and-ebuild/text.xml @@ -1,12 +1,11 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/emerge-and-ebuild/"> <chapter> <title>Emerge and Ebuild Relationships</title> <body> -<figure short="How emerge, ebuild and foo.ebuild interact" link="diagram.png"> -</figure> +<figure short="How emerge, ebuild and foo.ebuild interact" link="diagram.png" /> <p> The <c>emerge</c> program is a high level wrapper for <c>ebuild.sh</c> that handles @@ -15,7 +14,7 @@ dependency tracking, safe installs and uninstalls and so on. <c>emerge</c> calls and any eclasses. The <c>${D}</c> to <c>${ROOT}</c> install is handled by <c>emerge</c>. </p> -<todo>http://dev.gentoo.org/~g2boojum/portage.html</todo> +<todo>https://dev.gentoo.org/~g2boojum/portage.html</todo> </body> </chapter> diff --git a/general-concepts/features/text.xml b/general-concepts/features/text.xml deleted file mode 100644 index cba1cac..0000000 --- a/general-concepts/features/text.xml +++ /dev/null @@ -1,64 +0,0 @@ -<?xml version="1.0"?> -<guide self="general-concepts/features/"> -<chapter> -<title>FEATURES</title> - -<body> -<p> -The <c>FEATURES</c> variable specifies options which affect how Portage operates -and how packages are compiled. It is <b>not</b> used for settings which have a -substantial effect upon the resulting generated package. -</p> - -<p> -Relevant <c>FEATURES</c> for developers include: -</p> - -<table> - <tr> - <th>Feature</th> - <th>Explanation</th> - </tr> - <tr> - <ti><c>collision-protect</c></ti> - <ti> - Raise an error if an installing package attempts to overwrite a file which - is provided by a different package. - </ti> - </tr> - <tr> - <ti><c>noauto</c></ti> - <ti>When utilizing <c>ebuild</c>, only run the function requested.</ti> - </tr> - <tr> - <ti><c>sandbox</c></ti> - <ti>Enable the sandbox.</ti> - </tr> - <tr> - <ti><c>sign</c></ti> - <ti>GPG sign <c>Manifest</c> files.</ti> - </tr> - <tr> - <ti><c>strict</c></ti> - <ti> - Do some extra checks for potentially dangerous situations (eg missing - <c>Manifest</c> files). - </ti> - </tr> - <tr> - <ti><c>test</c></ti> - <ti>Enable the <c>src_test</c> phase.</ti> - </tr> - <tr> - <ti><c>userpriv</c></ti> - <ti>Drop to non-root privileges for certain phases.</ti> - </tr> - <tr> - <ti><c>usersandbox</c></ti> - <ti>Enables the sandbox even when running non-privileged.</ti> - </tr> -</table> - -</body> -</chapter> -</guide> diff --git a/general-concepts/filesystem/text.xml b/general-concepts/filesystem/text.xml index 9c52cc8..49d8652 100644 --- a/general-concepts/filesystem/text.xml +++ b/general-concepts/filesystem/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/filesystem/"> <chapter> <title>Filesystem</title> @@ -12,23 +12,25 @@ The basic filesystem layout and purpose is as follows: <li><c>/bin</c>: Boot-critical applications</li> <li><c>/etc</c>: System administrator controlled configuration files</li> <li><c>/lib</c>: Boot-critical libraries</li> - <li><c>/opt</c>: Binary-only applications.</li> + <li><c>/opt</c>: Non-standard layout applications</li> <li><c>/sbin</c>: System administrator boot-critical applications</li> <li><c>/tmp</c>: Temporary data</li> - <li><c>/usr</c>: General applications</li> - <ul> + <li><c>/usr</c>: General applications + <ul> <li><c>/usr/bin</c>: Applications</li> <li><c>/usr/lib</c>: Libraries</li> - <li><c>/usr/local</c>: Non-portage applications. <b>Ebuilds must not install here</b>.</li> + <li><c>/usr/local</c>: Non-Portage applications. <b>Ebuilds must not install here</b>.</li> <li><c>/usr/sbin</c>: Non-system-critical system administrator applications</li> <li><c>/usr/share</c>: Architecture independent application data and documentation</li> - </ul> - <li><c>/var</c>: Program generated data</li> - <ul> + </ul> + </li> + <li><c>/var</c>: Program generated data + <ul> <li><c>/var/cache</c>: Long term data which can be regenerated</li> <li><c>/var/lib</c>: General application generated data</li> <li><c>/var/log</c>: Log files</li> - </ul> + </ul> + </li> </ul> <p> @@ -43,12 +45,13 @@ Any binary which links against a library under <c>/usr</c> must itself go into </p> <p> -The <c>/opt</c> top-level should only be used for binary-only applications. -Binary-only applications must not be installed outside of <c>/opt</c>. +The <c>/opt</c> top-level should only be used for applications that +do not conform to the standard filesystem layout. This particularly includes +prebuilt software packages that expect being installed in a single directory. </p> <p> -The <c>/usr/local</c> hierarchy is for non-portage software. Ebuilds must not +The <c>/usr/local</c> hierarchy is for non-Portage software. Ebuilds must not attempt to put anything in here. </p> @@ -63,6 +66,7 @@ is additional work for the system administrator. In particular, non-text files and files that are not intended for system administrator usage should be moved to <c>/usr/share</c>. </p> +</body> <section> <title>FHS</title> @@ -76,7 +80,5 @@ much of our policy coincides with it. </body> </section> - -</body> </chapter> </guide> diff --git a/general-concepts/git-to-rsync/diagram.svg b/general-concepts/git-to-rsync/diagram.svg new file mode 100644 index 0000000..e695dbb --- /dev/null +++ b/general-concepts/git-to-rsync/diagram.svg @@ -0,0 +1,504 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + id="svg133" + version="1.1" + height="250" + width="700"> + <metadata + id="metadata139"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <defs + id="defs137" /> + <desc + id="desc2">Git to RSYNC Propagation</desc> + <rect + id="background" + fill="#eeeeee" + height="1000" + width="1000" + y="-10" + x="-10" /> + <rect + id="rect5" + stroke-width="2" + stroke="black" + fill="#ffcccc" + height="30" + width="80" + y="110" + x="10" /> + <text + id="text7" + y="130" + x="50" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Developers</text> + <line + id="line9" + stroke="black" + stroke-width="2" + y2="125" + x2="130" + y1="125" + x1="90" /> + <line + id="line11" + stroke="black" + stroke-width="2" + y2="120" + x2="122" + y1="125" + x1="130" /> + <line + id="line13" + stroke="black" + stroke-width="2" + y2="130" + x2="122" + y1="125" + x1="130" /> + <rect + id="rect15" + stroke-width="2" + stroke="black" + fill="#ffcccc" + height="30" + width="80" + y="60" + x="10" /> + <text + id="text17" + y="80" + x="50" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Developers</text> + <path + id="path19" + fill="none" + stroke="black" + stroke-width="2" + d="M 90 75 Q 110 75 110 100 Q 110 130 130 125" /> + <rect + id="rect21" + stroke-width="2" + stroke="black" + fill="#ffcccc" + height="30" + width="80" + y="160" + x="10" /> + <text + id="text23" + y="180" + x="50" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Developers</text> + <path + id="path25" + fill="none" + stroke="black" + stroke-width="2" + d="M 90 175 Q 110 175 110 150 Q 110 120 130 125" /> + <rect + id="rect27" + stroke-width="2" + stroke="black" + fill="#ffffff" + height="30" + width="80" + y="110" + x="130" /> + <text + id="text29" + y="130" + x="170" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Git Remote</text> + <line + id="line31" + stroke="black" + stroke-width="2" + y2="125" + x2="250" + y1="125" + x1="210" /> + <line + id="line33" + stroke="black" + stroke-width="2" + y2="120" + x2="242" + y1="125" + x1="250" /> + <line + id="line35" + stroke="black" + stroke-width="2" + y2="130" + x2="242" + y1="125" + x1="250" /> + <rect + id="rect37" + stroke-width="2" + stroke="black" + fill="#ffffff" + height="30" + width="80" + y="110" + x="250" /> + <text + id="text39" + y="123" + x="290" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Staging</text> + <text + id="text41" + y="135" + x="290" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Box</text> + <line + id="line43" + stroke="black" + stroke-width="2" + y2="125" + x2="370" + y1="125" + x1="330" /> + <line + id="line45" + stroke="black" + stroke-width="2" + y2="120" + x2="362" + y1="125" + x1="370" /> + <line + id="line47" + stroke="black" + stroke-width="2" + y2="130" + x2="362" + y1="125" + x1="370" /> + <rect + id="rect49" + stroke-width="2" + stroke="black" + fill="#ffffff" + height="30" + width="80" + y="110" + x="370" /> + <text + id="text51" + y="130" + x="410" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">rsync1</text> + <line + id="line53" + stroke="black" + stroke-width="2" + y2="70" + x2="482" + y1="75" + x1="490" /> + <line + id="line55" + stroke="black" + stroke-width="2" + y2="80" + x2="482" + y1="75" + x1="490" /> + <path + id="path57" + fill="none" + stroke="black" + stroke-width="2" + d="M 450 125 Q 470 125 470 100 Q 470 70 490 75" /> + <rect + id="rect59" + stroke-width="2" + stroke="black" + fill="#ccffcc" + height="30" + width="80" + y="60" + x="490" /> + <text + id="text61" + y="80" + x="530" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Public rsync</text> + <line + id="line63" + stroke="black" + stroke-width="2" + y2="125" + x2="490" + y1="125" + x1="450" /> + <line + id="line65" + stroke="black" + stroke-width="2" + y2="120" + x2="482" + y1="125" + x1="490" /> + <line + id="line67" + stroke="black" + stroke-width="2" + y2="130" + x2="482" + y1="125" + x1="490" /> + <rect + id="rect69" + stroke-width="2" + stroke="black" + fill="#ccffcc" + height="30" + width="80" + y="110" + x="490" /> + <text + id="text71" + y="130" + x="530" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Public rsync</text> + <line + id="line73" + stroke="black" + stroke-width="2" + y2="170" + x2="482" + y1="175" + x1="490" /> + <line + id="line75" + stroke="black" + stroke-width="2" + y2="180" + x2="482" + y1="175" + x1="490" /> + <path + id="path77" + fill="none" + stroke="black" + stroke-width="2" + d="M 450 125 Q 470 125 470 150 Q 470 180 490 175" /> + <rect + id="rect79" + stroke-width="2" + stroke="black" + fill="#ccffcc" + height="30" + width="80" + y="160" + x="490" /> + <text + id="text81" + y="180" + x="530" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Public rsync</text> + <line + id="line83" + stroke="black" + stroke-width="2" + y2="20" + x2="602" + y1="25" + x1="610" /> + <line + id="line85" + stroke="black" + stroke-width="2" + y2="30" + x2="602" + y1="25" + x1="610" /> + <path + id="path87" + fill="none" + stroke="black" + stroke-width="2" + d="M 570 75 Q 590 75 590 50 Q 590 20 610 25" /> + <rect + id="rect89" + stroke-width="2" + stroke="black" + fill="#ccccff" + height="30" + width="80" + y="10" + x="610" /> + <text + id="text91" + y="30" + x="650" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Users</text> + <line + id="line93" + stroke="black" + stroke-width="2" + y2="75" + x2="610" + y1="75" + x1="570" /> + <line + id="line95" + stroke="black" + stroke-width="2" + y2="70" + x2="602" + y1="75" + x1="610" /> + <line + id="line97" + stroke="black" + stroke-width="2" + y2="80" + x2="602" + y1="75" + x1="610" /> + <rect + id="rect99" + stroke-width="2" + stroke="black" + fill="#ccccff" + height="30" + width="80" + y="60" + x="610" /> + <text + id="text101" + y="80" + x="650" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Users</text> + <line + id="line103" + stroke="black" + stroke-width="2" + y2="125" + x2="610" + y1="125" + x1="570" /> + <line + id="line105" + stroke="black" + stroke-width="2" + y2="120" + x2="602" + y1="125" + x1="610" /> + <line + id="line107" + stroke="black" + stroke-width="2" + y2="130" + x2="602" + y1="125" + x1="610" /> + <rect + id="rect109" + stroke-width="2" + stroke="black" + fill="#ccccff" + height="30" + width="80" + y="110" + x="610" /> + <text + id="text111" + y="130" + x="650" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Users</text> + <line + id="line113" + stroke="black" + stroke-width="2" + y2="175" + x2="610" + y1="175" + x1="570" /> + <line + id="line115" + stroke="black" + stroke-width="2" + y2="170" + x2="602" + y1="175" + x1="610" /> + <line + id="line117" + stroke="black" + stroke-width="2" + y2="180" + x2="602" + y1="175" + x1="610" /> + <rect + id="rect119" + stroke-width="2" + stroke="black" + fill="#ccccff" + height="30" + width="80" + y="160" + x="610" /> + <text + id="text121" + y="180" + x="650" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Users</text> + <line + id="line123" + stroke="black" + stroke-width="2" + y2="220" + x2="602" + y1="225" + x1="610" /> + <line + id="line125" + stroke="black" + stroke-width="2" + y2="230" + x2="602" + y1="225" + x1="610" /> + <path + id="path127" + fill="none" + stroke="black" + stroke-width="2" + d="M 570 175 Q 590 175 590 200 Q 590 230 610 225" /> + <rect + id="rect129" + stroke-width="2" + stroke="black" + fill="#ccccff" + height="30" + width="80" + y="210" + x="610" /> + <text + id="text131" + y="230" + x="650" + style="text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">Users</text> +</svg> diff --git a/general-concepts/git-to-rsync/text.xml b/general-concepts/git-to-rsync/text.xml new file mode 100644 index 0000000..b8f7dce --- /dev/null +++ b/general-concepts/git-to-rsync/text.xml @@ -0,0 +1,41 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="general-concepts/git-to-rsync/"> +<chapter> +<title>Git to RSYNC</title> + +<body> + +<p> + Changes made to the tree are propagated to the users in stages: +</p> + +<ul> + <li> + Developer commits to local Git clone and pushes to central remote + Git repository. Commits and pushes are signed using Git + mechanisms based on GPG. + </li> + <li> + Staging box syncs from central Git repository, generates the metadata cache, ChangeLogs and signed Manifests from Git history. + </li> + <li> + <c>rsync1</c> syncs from the staging box. + </li> + <li> + Public rsync servers sync from <c>rsync1</c>. + </li> + <li> + Users sync from the public rsync servers. + </li> +</ul> + +<figure short="Git to RSYNC Propagation" link="diagram.png" + caption="Diagram showing Git to RSYNC Propagation" /> + +<p> + The <c>emerge-websync</c> snapshot is made daily from the staging box. +</p> + +</body> +</chapter> +</guide> diff --git a/general-concepts/herds-and-projects/text.xml b/general-concepts/herds-and-projects/text.xml deleted file mode 100644 index e030150..0000000 --- a/general-concepts/herds-and-projects/text.xml +++ /dev/null @@ -1,32 +0,0 @@ -<?xml version="1.0"?> -<guide self="general-concepts/herds-and-projects/"> -<chapter> -<title>Herds and Projects</title> - -<body> - -<p> -A <e>herd</e> is a collection of packages with an associated set of maintainers. -It can happen for example because of retirement that a herd has no developers -but this should be avoided if at all possible. A herd has an associated email -address which can be used for bugzilla assignments. This email address is -<b>not</b> always <c>herdname@gentoo.org</c> <d/> for example, because of the -way Gentoo's email aliases are set up, the <c>cron</c> herd use -<c>cron-bugs@gentoo.org</c> (aliases cannot match system usernames). -</p> - -<p> -A <e>project</e> is a group formed for handling a particular general area. A project -may have herds associated with it. -</p> - -<p> -Sometimes herd and project names overlap <d/> for example, the <c>sparc</c> project -has an associated <c>sparc</c> herd which maintains sparc-specific packages (such -as the <c>silo</c> bootloader). This is <e>not</e> always the case. -</p> - -</body> -</chapter> -</guide> - diff --git a/general-concepts/install-destinations/text.xml b/general-concepts/install-destinations/text.xml index cf9c278..5413ebc 100644 --- a/general-concepts/install-destinations/text.xml +++ b/general-concepts/install-destinations/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/install-destinations/"> <chapter> <title>Install Destinations</title> diff --git a/general-concepts/licenses/text.xml b/general-concepts/licenses/text.xml index ba75969..a9fb702 100644 --- a/general-concepts/licenses/text.xml +++ b/general-concepts/licenses/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/licenses/"> <chapter> <title>Licenses</title> @@ -6,8 +6,31 @@ <body> <p> All ebuilds must specify a <c>LICENSE</c> (note the American English -spelling) variable. The value of this variable must be the name of a -file in the Portage tree's <c>licenses/</c> directory. +spelling) variable. The license names listed in this variable must +match files existing in the repository's <c>licenses/</c> directory. +</p> + +<p> +The value of this variable should include all licenses pertaining to the +"corresponding source" of the files installed by the package. This includes +all their source code, but also all scripts used to control compilation and +installation. If the package has a "main license" <d/> i.e. a license covering +most of its files <d/> then this should be listed first. +</p> + +<p> +If some parts of the package are installed only conditionally, or their +license depends on the USE flag combination, you can use USE conditionals +in <c>LICENSE</c>: +</p> + +<codesample lang="ebuild"> +LICENSE="LGPL-2.1+ tools? ( GPL-2+ )" +</codesample> + +<p> +If the package sources include additional files that are neither installed +nor used at build time, their license should not be listed. </p> <p> @@ -18,8 +41,191 @@ be used) then use the following syntax: <codesample lang="ebuild"> LICENSE="|| ( foo bar )" </codesample> +</body> + +<section> +<title>License-implied restrictions</title> +<body> + +<p> +Non-free licenses may impose additional restrictions that need to be stated +in the ebuild. In order to identify such restrictions correctly, it is necessary +to analyze relevant license(s) and determine applicable clauses based +on the files contained in upstream packages. Note that upstreams may use +the same license for multiple products, with some restrictions not being +applicable to the ebuild in question. +</p> + +<p> +If the license of a package does not explicitly permit redistributing distfiles +found in <c>SRC_URI</c>, the corresponding ebuilds must have +<c>RESTRICT=mirror</c> to prevent the affected files from being copied to Gentoo +mirrors. In some cases, the license permits redistributing unmodified original +archives only <d/> in that case, <c>SRC_URI</c> must not contain modified +or repackaged upstream archives, and all changes must be applied via patching +in appropriate ebuild phases. +</p> + +<p> +If the license does not permit distributing Gentoo binary packages built using +the ebuild, with or without source modifications, it must have +<c>RESTRICT=bindist</c>. This is also the case if restrictions are set based +on the cost of redistribution (e.g. the license prohibits selling the product). +</p> + +<p> +Some EULAs may also require the user to fetch distfiles manually, in which case +<c>RESTRICT=fetch</c> is necessary. Note that <c>RESTRICT=fetch</c> implies +<c>RESTRICT=mirror</c>. +</p> + +</body> +</section> + +<section> +<title>Determining the correct license</title> +<body> + +<warning> +Do not trust the license indicated by GitHub or other sites that use automation +to guess the license! The information presented may be incomplete and/or +incorrect. The +<uri link="https://developer.github.com/v3/licenses/#get-the-contents-of-a-repositorys-license"> +GitHub License API</uri> for example can only return a single license for a +given repository. +</warning> + +<p> +To establish the correct value of <c>LICENSE</c>, you need to trace +the licenses of all installed files. Normally, the licenses of output +files (compiled executables, generated files) are implied +by the licenses of the relevant input files. +</p> + +<p> +When looking for license information, the following should be +considered: +</p> + +<ol> + <li> + <c>COPYING*</c> and <c>LICENSE*</c> files distributed with + the package + </li> + <li> + explicit statements in documentation + </li> + <li> + explicit license notices in source and data files + </li> +</ol> + +<p> +The latter (more specific) options take precedence over the former. +In particular, <c>COPYING*</c> files are frequently included as hardcopies +of applicable licenses but the exact application of licenses and their +versions are specified elsewhere. +</p> + +<p> +If the package does not indicate any license, then you should contact +the author for clarification. Adding packages with no explicit license +statement is strongly discouraged. If they are present already, they +ought to have <c>all-rights-reserved</c> license, +and <c>RESTRICT="bindist mirror"</c>. +</p> + +</body> +</section> + +<section> +<title>Detecting upstream license problems</title> +<body> + +<p> +Please watch out for upstream licensing problems and report them +upstream. +You may ask the Gentoo licenses team for guidance. In general, it is +preferable to wait for upstream to resolve the issue and release a new +version. Do not add packages that seem to include license term +violations! +</p> + +<p> +Common license problems include but are not limited to: +</p> + +<ol> + <li> + <p> + Including third party code without appropriate copyright notices. + Practically all licenses (with notable exception of public + domain-alike) require attribution, and some require copying + original copyright notices verbatim. + </p> + </li> + <li> + <p> + Combining incompatible licenses. When you are combining multiple + files using different licenses into a single executable, those + licenses need to be compatible. For example, it is not possible + to combine proprietary code with copyleft licenses (e.g. GPL). + It is also incorrect to combine GPL-2 (only) and GPL-3 code. + </p> + </li> + <li> + <p> + Dynamically linking incompatible executables. Arguably, some + licenses also apply restriction on dynamic linking between + executables and shared libraries. For example, normally you can't + link GPL executables with OpenSSL. The same restriction does not + apply to LGPL, and some projects are adding specific linking + exceptions to their GPL usage. + </p> + </li> + <li> + <p> + Wrong or incomplete license information about a project. Upstream + may indicate the wrong effective license for a project (e.g. + in README. For example, upstream may indicate that the project + is licensed as GPL-2+ while some of the source code files use + GPL-3+ license. + </p> + </li> +</ol> + +</body> +</section> + +<section> +<title>GPL-x vs GPL-x+</title> +<body> -<subsection> +<p> +FSF licenses (GPL, LGPL, AGPL, FDL) occur in two variants: the 'vN only' +and 'vN or later' variants. In Gentoo, the licenses of the latter variants +are denoted by appending +a plus sign (+) to their respective license notations of the former variant, +e.g. <c>GPL-2+</c> and <c>GPL-2</c>. +</p> + +<p> +Determining the correct variant usually requires looking for copyright +notices in the code. For example, the following copyright notice +indicates <c>GPL-2+</c> license: +</p> + +<pre> + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License as + * published by the Free Software Foundation; either version 2 of + * the License, or (at your option) any later version. +</pre> + +</body> +</section> + +<section> <title>Adding New Licenses</title> <body> @@ -31,7 +237,7 @@ PDF files rather than plain text <d/> this should only be done if we are legally required to do so. Finally you need to check if your license should be added to a license group as listed in $PORTDIR/profiles/license_groups. For more information see the -<uri link="https://wiki.gentoo.org/wiki/GLEP:23">GLEP 23</uri> +<uri link="https://www.gentoo.org/glep/glep-0023.html">GLEP 23</uri>. </p> <p> @@ -41,9 +247,42 @@ only do so if the license could be considered 'questionable' or if you are unsure as to the meaning of any part of it. </p> +<p> +When adding a new license, it should be checked whether there is an established +name in the <uri link="https://spdx.org/licenses/">SPDX license list</uri>. +However, Gentoo does not consider the Software Package Data Exchange to be an +authoritative standard, so we may sometimes deviate from it, e.g., if their +"short identifier" is excessively long. Also, we generally don't rename our +existing identifiers. +</p> + </body> -</subsection> -</body> +</section> + +<section> +<title>Further reading</title> +<body> +<p> +The following resources are recommended as source of more information +on copyright and licensing: +</p> + +<ul> + <li> + <uri link="https://dwheeler.com/essays/floss-license-slide.html"> + David A. Wheeler, The Free-Libre / Open Source Software (FLOSS) + License Slide + </uri> + </li> + <li> + <uri link="https://www.gnu.org/licenses/license-compatibility.en.html"> + Richard Stallman, License Compatibility and Relicensing + </uri> + </li> +</ul> + +</body> +</section> </chapter> </guide> diff --git a/general-concepts/linguas/text.xml b/general-concepts/linguas/text.xml deleted file mode 100644 index d44a879..0000000 --- a/general-concepts/linguas/text.xml +++ /dev/null @@ -1,13 +0,0 @@ -<?xml version="1.0"?> -<guide self="general-concepts/linguas/"> -<chapter> -<title>Linguas</title> - -<body> -<todo> -Write this. From vapier: "used to specify languages users wish to have support for. USE=nls covers generally natural language support, but LINGUAS covers specific languages (see the games-rpg/nwn for example). the variable is expanded for USE access in ebuilds. LINGUAS=de would automatically add 'linguas_de' to USE." We also need strip-linguas examples. -</todo> -</body> - -</chapter> -</guide> diff --git a/general-concepts/mailing-lists/text.xml b/general-concepts/mailing-lists/text.xml new file mode 100644 index 0000000..8787b13 --- /dev/null +++ b/general-concepts/mailing-lists/text.xml @@ -0,0 +1,80 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="general-concepts/mailing-lists/"> +<chapter> +<title>Mailing Lists</title> +<body> + +<p> +Mailing lists are the most important communication media in Gentoo. +They are used to announce events, discuss changes, review code. Use +of mailing lists is explicitly required by some of the processes such +as package last rites. +</p> + +<p> +The complete list of Gentoo mailing lists can be found in the +<uri link="https://www.gentoo.org/get-involved/mailing-lists/">mailing +list</uri> section of the Gentoo website. All mailing lists are +archived. The archives for the public lists can be found on +the <uri link="https://archives.gentoo.org/">mailing list archives</uri> +site. The data from the non-public archives can be provided +by the Infrastructure team at the request of a developer. +</p> +</body> + +<section> +<title>Primary developer mailing lists</title> +<body> + +<p> +There are five primary lists intended for Gentoo developers +(and contributors): +</p> + +<ul> + <li>gentoo-core — internal non-public Gentoo developer list</li> + <li>gentoo-dev — public technical discussion list</li> + <li>gentoo-dev-announce — developer announcement list</li> + <li>gentoo-nfp — Gentoo Foundation discussion list</li> + <li>gentoo-project — public non-technical discussion list</li> +</ul> + +<p> +Most of the discussions take place on the gentoo-dev and gentoo-project +mailing lists. Strictly technical topics (e.g. ebuild development, +system behavior) go into gentoo-dev, while non-technical topics +(e.g. organizational matters) go into gentoo-project. Both lists are +public and open to everyone. Developers are strongly encouraged +to follow these lists. +</p> + +<p> +The gentoo-nfp list is used for affairs strictly related to the Gentoo +Foundation. For example, this includes funding and legal affairs. +</p> + +<p> +The gentoo-dev-announce is used for important announcements that affect +developers, for example major policy changes, project news. This list +is also used to announce last rites and packages needing new +maintainers. gentoo-dev-announce is not meant to accept replies, so +all messages sent to it must be cross-posted to another mailing list +and have their Reply-To header set to that list. Messages without Reply-To +are rejected, the remaining messages are moderated to prevent accidental +replies from coming through. +</p> + +<p> +The gentoo-core mailing list is restricted to developers. +It is generally used when developers wish to share information regarding +their personal situation with other developers and to discuss sensitive +matters that cannot be published at the time. The list is non-public +and it is forbidden to publicly discuss messages from -core, forward +them or cross-post to another mailing list. All developers are +subscribed to it. +</p> + +</body> +</section> +</chapter> +</guide> diff --git a/general-concepts/manifest/text.xml b/general-concepts/manifest/text.xml index 665c259..bee1651 100644 --- a/general-concepts/manifest/text.xml +++ b/general-concepts/manifest/text.xml @@ -1,80 +1,80 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/manifest/"> <chapter> <title>Manifest</title> -<body> - <section> <title>Generating the Manifest</title> <body> <p> -In the tree, every package has a <c>Manifest</c> file. This file lives in the same -directory as the ebuilds for the package. The <c>Manifest</c> file contains digests -(currently RMD160, SHA1, SHA256, SHA512 and WHIRLPOOL) and file size data for every -file in the directory and any subdirectories. This is used to verify integrity. -The <c>Manifest</c> may also be digitally signed. +In the tree, every package has a <c>Manifest</c> file. This file lives +in the same directory as the ebuilds for the package. The <c>Manifest</c> file +contains digests (the current list can be found in <c>metadata/layout.conf</c> +as <c>manifest-hashes</c>) and file size data for every distfile used +by the package. This is used to verify integrity upon fetching them. </p> <p> -To generate the <c>Manifest</c>, use <c>ebuild foo.ebuild manifest</c>. When -committing, the <c>Manifest</c> file must be regenerated to handle any CVS keyword -expansion changes <d/> <c>repoman</c> will do this automatically. +To generate the <c>Manifest</c>, use <c>ebuild foo.ebuild manifest</c> or +<c>pkgdev manifest -m</c>. You may want to set <c>GENTOO_MIRRORS=</c> while +calling it to fetch distfiles from their original locations immediately. </p> </body> -</section> -<section> -<title>Signing the Manifest using your GPG key</title> +<subsection> +<title>Thin and thick Manifests</title> <body> <p> -Requirements: +There are two kinds of Manifest files in Gentoo: thin Manifests that are used +in the development repositories, and thick Manifests that are distributed +via rsync to end users. Thin Manifests are described above. </p> -<ul> - <li>>=sys-apps/portage-2.0.51_pre10</li> - <li>>=app-crypt/gnupg-1.2.4</li> -</ul> - <p> -Key Setup: +Thick Manifests add checksums for all files in the repository, and an OpenPGP +signature. This provides both for integrity and authenticity checking when +the repository is transmitted over insecure channels. Thick Manifests +are automatically generated on Gentoo Infrastructure, and require no specific +action from developers. </p> +</body> +</subsection> + +<subsection> +<title>Updating <c>Manifest</c> files</title> +<body> -<ul> - <li> - <uri link="http://www.gentoo.org/doc/en/gnupg-user.xml#doc_chap2">Create</uri> - a new DSA GnuPG key with at least a 1024 bit keylength, an expiration - period no longer than 6 months and a good passphrase. - </li> - <li> - <uri link="http://www.gentoo.org/doc/en/gnupg-user.xml#doc_chap3">Upload</uri> - the key to a keyserver. - </li> -</ul> +<p> +Updating existing entries within a manifest must be done with care. Upstream +changing the tarball in-place without a new filename could be an innocent +respin of the tarball, or it could indicate either the previous or the new +tarball is malicious. +</p> <p> -Portage Configuration: +Developers should diff the old and new versions of the distfile, comparing +the two, and note the differences in the commit message updating the +<c>Manifest</c> to indicate both what happened (if any context is known) and +also what differences between the two distfiles have been ascertained. </p> -<ul> - <li> - Set <path>PORTAGE_GPG_DIR</path> to your <path>~/.gnupg/</path> directory - (or the directory where the keyring with your new key is). - </li> - <li>Set <path>PORTAGE_GPG_KEY</path> to the key id of your new key.</li> - <li>Set FEATURES="sign".</li> -</ul> +<p> +Please note that if upstream made any changes affecting the built +package or it had substantial differences, you need to also bump the ebuild's +revision. Finally, remember to remove the ebuilds that are associated with the +old distfile, or regenerate their checksums in <c>Manifest</c>, if there +are any. This is necessary because these ebuilds will cause checksum +mismatch errors as the checksum recorded in the manifest file no +longer matches the computed checksum of the fetched distfile. +</p> <p> -Now you should be able to sign your Manifests on repoman commit. Repoman will -ask you for your passphrase before committing the Manifest. This step is -<e>after</e> it has committed the other files. At the moment repoman doesn't -check if the Manifest is already signed, so others are able to "unsign" your -package later. This will change before signing is made mandatory. +Special care is also required with regard to +<uri link="::general-concepts/mirrors/#Replacing Automatically Mirrored Files"> +mirrors</uri>. </p> </body> +</subsection> </section> - -</body> </chapter> </guide> diff --git a/general-concepts/mirrors/diagram.svg b/general-concepts/mirrors/diagram.svg index 0af1f1c..c98b830 100644 --- a/general-concepts/mirrors/diagram.svg +++ b/general-concepts/mirrors/diagram.svg @@ -1,521 +1,496 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> <svg xmlns:dc="http://purl.org/dc/elements/1.1/" - xmlns:cc="http://web.resource.org/cc/" + xmlns:cc="http://creativecommons.org/ns#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" - xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" - xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" - sodipodi:docbase="/home/plasmaroo" - sodipodi:docname="diagram.svg" - inkscape:version="0.41" - sodipodi:version="0.32" - version="1.0" - x="0.0000000" - y="0.0000000" - width="700.00000px" - height="250.00000px" + id="svg1546" viewBox="0 0 700 250" - id="svg1546"> + height="250.00000px" + width="700.00000px" + y="0.0000000" + x="0.0000000" + version="1.0"> <metadata id="metadata71"> - <rdf:RDF - id="RDF73"> + <rdf:RDF> <cc:Work - id="Work75" rdf:about=""> - <dc:format - id="format77">image/svg+xml</dc:format> + <dc:format>image/svg+xml</dc:format> <dc:type - rdf:resource="http://purl.org/dc/dcmitype/StillImage" - id="type79" /> + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> </cc:Work> </rdf:RDF> </metadata> - <sodipodi:namedview - inkscape:current-layer="svg1546" - inkscape:window-y="264" - inkscape:window-x="164" - inkscape:cy="81.156529" - inkscape:cx="343.48587" - inkscape:zoom="0.97294509" - inkscape:window-height="541" - inkscape:window-width="968" - inkscape:pageshadow="2" - inkscape:pageopacity="1.0000000" - borderopacity="1.0" - bordercolor="#666666" - pagecolor="#eeeeee" - id="base" /> <defs id="defs1680" /> <desc - id="desc1548">CVS to RSYNC Propagation</desc> + id="desc1548">Git to RSYNC Propagation</desc> <rect - y="0.24284256" - x="-2.0556145" - height="260.03522" - width="710.21484" + style="fill:#eeeeee;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000" id="rect1360" - style="fill:#eeeeee;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000" /> + width="710.21484" + height="260.03522" + x="-2.0556145" + y="0.24284256" /> <rect - width="80.000000" - height="30.000000" - x="10.000000" - y="110.00000" + id="rect1551" style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000" - id="rect1551" /> + y="110.00000" + x="10.000000" + height="30.000000" + width="80.000000" /> <text - x="50" + id="text1553" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="130" - style="text-anchor:middle" - id="text1553">Developers</text> + x="50">Developers</text> <line - id="line1555" - stroke="black" - stroke-width="2" - y2="125.00000" - x2="130.00000" - y1="125.00000" + style="stroke:#000000;stroke-width:2.0000000" x1="90.000000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1557" - stroke="black" - stroke-width="2" - y2="120.00000" - x2="122.00000" y1="125.00000" - x1="130.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1559" - stroke="black" + x2="130.00000" + y2="125.00000" stroke-width="2" - y2="130.00000" - x2="122.00000" + stroke="black" + id="line1555" /> + <line + style="stroke:#000000;stroke-width:2.0000000" + x1="130.00000" y1="125.00000" + x2="122.00000" + y2="120.00000" + stroke-width="2" + stroke="black" + id="line1557" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="130.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="125.00000" + x2="122.00000" + y2="130.00000" + stroke-width="2" + stroke="black" + id="line1559" /> <rect - width="80.000000" - height="30.000000" - x="10.000000" - y="60.000000" + id="rect1561" style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000" - id="rect1561" /> + y="60.000000" + x="10.000000" + height="30.000000" + width="80.000000" /> <text - x="50" + id="text1563" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="80" - style="text-anchor:middle" - id="text1563">Developers</text> + x="50">Developers</text> <path - d="M 90.000000,75.000000 C 103.33333,75.000000 110.00000,83.333333 110.00000,100.00000 C 110.00000,120.00000 116.66667,128.33333 130.00000,125.00000" + id="path1565" style="fill:none;stroke:#000000;stroke-width:2.0000000" - id="path1565" /> + d="M 90.000000,75.000000 C 103.33333,75.000000 110.00000,83.333333 110.00000,100.00000 C 110.00000,120.00000 116.66667,128.33333 130.00000,125.00000" /> <rect - width="80.000000" - height="30.000000" - x="10.000000" - y="160.00000" + id="rect1567" style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000" - id="rect1567" /> + y="160.00000" + x="10.000000" + height="30.000000" + width="80.000000" /> <text - x="50" + id="text1569" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="180" - style="text-anchor:middle" - id="text1569">Developers</text> + x="50">Developers</text> <path - d="M 90.000000,175.00000 C 103.33333,175.00000 110.00000,166.66667 110.00000,150.00000 C 110.00000,130.00000 116.66667,121.66667 130.00000,125.00000" + id="path1571" style="fill:none;stroke:#000000;stroke-width:2.0000000" - id="path1571" /> + d="M 90.000000,175.00000 C 103.33333,175.00000 110.00000,166.66667 110.00000,150.00000 C 110.00000,130.00000 116.66667,121.66667 130.00000,125.00000" /> <rect - width="80.000000" - height="30.000000" - x="130.00000" - y="110.00000" + id="rect1573" style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000" - id="rect1573" /> + y="110.00000" + x="130.00000" + height="30.000000" + width="80.000000" /> <text - x="170" + id="text1575" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="130" - style="text-anchor:middle" - id="text1575">dev.gentoo</text> + x="170">dev.gentoo</text> <line - id="line1577" - stroke="black" - stroke-width="2" - y2="125.00000" - x2="250.00000" - y1="125.00000" + style="stroke:#000000;stroke-width:2.0000000" x1="210.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1579" - stroke="black" - stroke-width="2" - y2="120.00000" - x2="242.00000" y1="125.00000" - x1="250.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1581" - stroke="black" + x2="250.00000" + y2="125.00000" stroke-width="2" - y2="130.00000" - x2="242.00000" + stroke="black" + id="line1577" /> + <line + style="stroke:#000000;stroke-width:2.0000000" + x1="250.00000" y1="125.00000" + x2="242.00000" + y2="120.00000" + stroke-width="2" + stroke="black" + id="line1579" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="250.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="125.00000" + x2="242.00000" + y2="130.00000" + stroke-width="2" + stroke="black" + id="line1581" /> <rect - width="80.000000" - height="30.000000" - x="250.00000" - y="110.00000" + id="rect1583" style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000" - id="rect1583" /> + y="110.00000" + x="250.00000" + height="30.000000" + width="80.000000" /> <text - x="290" + id="text1585" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="123" - style="text-anchor:middle" - id="text1585">Staging</text> + x="290">Staging</text> <text - x="290" + id="text1587" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="135" - style="text-anchor:middle" - id="text1587">Box</text> + x="290">Box</text> <line - id="line1589" - stroke="black" - stroke-width="2" - y2="125.00000" - x2="370.00000" - y1="125.00000" + style="stroke:#000000;stroke-width:2.0000000" x1="330.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1591" - stroke="black" - stroke-width="2" - y2="120.00000" - x2="362.00000" y1="125.00000" - x1="370.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1593" - stroke="black" + x2="370.00000" + y2="125.00000" stroke-width="2" - y2="130.00000" - x2="362.00000" + stroke="black" + id="line1589" /> + <line + style="stroke:#000000;stroke-width:2.0000000" + x1="370.00000" y1="125.00000" + x2="362.00000" + y2="120.00000" + stroke-width="2" + stroke="black" + id="line1591" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="370.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="125.00000" + x2="362.00000" + y2="130.00000" + stroke-width="2" + stroke="black" + id="line1593" /> <rect - width="80.000000" - height="30.000000" - x="370.00000" - y="110.00000" + id="rect1595" style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000" - id="rect1595" /> + y="110.00000" + x="370.00000" + height="30.000000" + width="80.000000" /> <text - x="410" + id="text1597" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="130" - style="text-anchor:middle" - id="text1597">OSU Mirrors</text> + x="410">OSU Mirrors</text> <line - id="line1599" - stroke="black" - stroke-width="2" - y2="70.000000" - x2="482.00000" - y1="75.000000" + style="stroke:#000000;stroke-width:2.0000000" x1="490.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1601" - stroke="black" - stroke-width="2" - y2="80.000000" - x2="482.00000" y1="75.000000" + x2="482.00000" + y2="70.000000" + stroke-width="2" + stroke="black" + id="line1599" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="490.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="75.000000" + x2="482.00000" + y2="80.000000" + stroke-width="2" + stroke="black" + id="line1601" /> <path - d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,116.66667 470.00000,100.00000 C 470.00000,80.000000 476.66667,71.666667 490.00000,75.000000" + id="path1603" style="fill:none;stroke:#000000;stroke-width:2.0000000" - id="path1603" /> + d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,116.66667 470.00000,100.00000 C 470.00000,80.000000 476.66667,71.666667 490.00000,75.000000" /> <rect - width="80.000000" - height="30.000000" - x="490.00000" - y="60.000000" + id="rect1605" style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000" - id="rect1605" /> + y="60.000000" + x="490.00000" + height="30.000000" + width="80.000000" /> <text - x="530" + id="text1607" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="80" - style="text-anchor:middle" - id="text1607">Public mirror</text> + x="530">Public mirror</text> <line - id="line1609" - stroke="black" - stroke-width="2" - y2="125.00000" - x2="490.00000" - y1="125.00000" + style="stroke:#000000;stroke-width:2.0000000" x1="450.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1611" - stroke="black" - stroke-width="2" - y2="120.00000" - x2="482.00000" y1="125.00000" - x1="490.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1613" - stroke="black" + x2="490.00000" + y2="125.00000" stroke-width="2" - y2="130.00000" - x2="482.00000" + stroke="black" + id="line1609" /> + <line + style="stroke:#000000;stroke-width:2.0000000" + x1="490.00000" y1="125.00000" + x2="482.00000" + y2="120.00000" + stroke-width="2" + stroke="black" + id="line1611" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="490.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="125.00000" + x2="482.00000" + y2="130.00000" + stroke-width="2" + stroke="black" + id="line1613" /> <rect - width="80.000000" - height="30.000000" - x="490.00000" - y="110.00000" + id="rect1615" style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000" - id="rect1615" /> + y="110.00000" + x="490.00000" + height="30.000000" + width="80.000000" /> <text - x="530" + id="text1617" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="130" - style="text-anchor:middle" - id="text1617">Public mirror</text> + x="530">Public mirror</text> <line - id="line1619" - stroke="black" - stroke-width="2" - y2="170.00000" - x2="482.00000" - y1="175.00000" + style="stroke:#000000;stroke-width:2.0000000" x1="490.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1621" - stroke="black" - stroke-width="2" - y2="180.00000" - x2="482.00000" y1="175.00000" + x2="482.00000" + y2="170.00000" + stroke-width="2" + stroke="black" + id="line1619" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="490.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="175.00000" + x2="482.00000" + y2="180.00000" + stroke-width="2" + stroke="black" + id="line1621" /> <path - d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,133.33333 470.00000,150.00000 C 470.00000,170.00000 476.66667,178.33333 490.00000,175.00000" + id="path1623" style="fill:none;stroke:#000000;stroke-width:2.0000000" - id="path1623" /> + d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,133.33333 470.00000,150.00000 C 470.00000,170.00000 476.66667,178.33333 490.00000,175.00000" /> <rect - width="80.000000" - height="30.000000" - x="490.00000" - y="160.00000" + id="rect1625" style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000" - id="rect1625" /> + y="160.00000" + x="490.00000" + height="30.000000" + width="80.000000" /> <text - x="530" + id="text1627" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="180" - style="text-anchor:middle" - id="text1627">Public mirror</text> + x="530">Public mirror</text> <line - id="line1629" - stroke="black" - stroke-width="2" - y2="20.000000" - x2="602.00000" - y1="25.000000" + style="stroke:#000000;stroke-width:2.0000000" x1="610.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1631" - stroke="black" - stroke-width="2" - y2="30.000000" - x2="602.00000" y1="25.000000" + x2="602.00000" + y2="20.000000" + stroke-width="2" + stroke="black" + id="line1629" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="610.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="25.000000" + x2="602.00000" + y2="30.000000" + stroke-width="2" + stroke="black" + id="line1631" /> <path - d="M 570.00000,75.000000 C 583.33333,75.000000 590.00000,66.666667 590.00000,50.000000 C 590.00000,30.000000 596.66667,21.666667 610.00000,25.000000" + id="path1633" style="fill:none;stroke:#000000;stroke-width:2.0000000" - id="path1633" /> + d="M 570.00000,75.000000 C 583.33333,75.000000 590.00000,66.666667 590.00000,50.000000 C 590.00000,30.000000 596.66667,21.666667 610.00000,25.000000" /> <rect - width="80.000000" - height="30.000000" - x="610.00000" - y="10.000000" + id="rect1635" style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" - id="rect1635" /> + y="10.000000" + x="610.00000" + height="30.000000" + width="80.000000" /> <text - x="650" + id="text1637" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="30" - style="text-anchor:middle" - id="text1637">Users</text> + x="650">Users</text> <line - id="line1639" - stroke="black" - stroke-width="2" - y2="75.000000" - x2="610.00000" - y1="75.000000" + style="stroke:#000000;stroke-width:2.0000000" x1="570.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1641" - stroke="black" - stroke-width="2" - y2="70.000000" - x2="602.00000" y1="75.000000" - x1="610.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1643" - stroke="black" + x2="610.00000" + y2="75.000000" stroke-width="2" - y2="80.000000" - x2="602.00000" + stroke="black" + id="line1639" /> + <line + style="stroke:#000000;stroke-width:2.0000000" + x1="610.00000" y1="75.000000" + x2="602.00000" + y2="70.000000" + stroke-width="2" + stroke="black" + id="line1641" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="610.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="75.000000" + x2="602.00000" + y2="80.000000" + stroke-width="2" + stroke="black" + id="line1643" /> <rect - width="80.000000" - height="30.000000" - x="610.00000" - y="60.000000" + id="rect1645" style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" - id="rect1645" /> + y="60.000000" + x="610.00000" + height="30.000000" + width="80.000000" /> <text - x="650" + id="text1647" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="80" - style="text-anchor:middle" - id="text1647">Users</text> + x="650">Users</text> <line - id="line1649" - stroke="black" - stroke-width="2" - y2="125.00000" - x2="610.00000" - y1="125.00000" + style="stroke:#000000;stroke-width:2.0000000" x1="570.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1651" - stroke="black" - stroke-width="2" - y2="120.00000" - x2="602.00000" y1="125.00000" - x1="610.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1653" - stroke="black" + x2="610.00000" + y2="125.00000" stroke-width="2" - y2="130.00000" - x2="602.00000" + stroke="black" + id="line1649" /> + <line + style="stroke:#000000;stroke-width:2.0000000" + x1="610.00000" y1="125.00000" + x2="602.00000" + y2="120.00000" + stroke-width="2" + stroke="black" + id="line1651" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="610.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="125.00000" + x2="602.00000" + y2="130.00000" + stroke-width="2" + stroke="black" + id="line1653" /> <rect - width="80.000000" - height="30.000000" - x="610.00000" - y="110.00000" + id="rect1655" style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" - id="rect1655" /> + y="110.00000" + x="610.00000" + height="30.000000" + width="80.000000" /> <text - x="650" + id="text1657" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="130" - style="text-anchor:middle" - id="text1657">Users</text> + x="650">Users</text> <line - id="line1659" - stroke="black" - stroke-width="2" - y2="175.00000" - x2="610.00000" - y1="175.00000" + style="stroke:#000000;stroke-width:2.0000000" x1="570.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1661" - stroke="black" - stroke-width="2" - y2="170.00000" - x2="602.00000" y1="175.00000" - x1="610.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1663" - stroke="black" + x2="610.00000" + y2="175.00000" stroke-width="2" - y2="180.00000" - x2="602.00000" + stroke="black" + id="line1659" /> + <line + style="stroke:#000000;stroke-width:2.0000000" + x1="610.00000" y1="175.00000" + x2="602.00000" + y2="170.00000" + stroke-width="2" + stroke="black" + id="line1661" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="610.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="175.00000" + x2="602.00000" + y2="180.00000" + stroke-width="2" + stroke="black" + id="line1663" /> <rect - width="80.000000" - height="30.000000" - x="610.00000" - y="160.00000" + id="rect1665" style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" - id="rect1665" /> + y="160.00000" + x="610.00000" + height="30.000000" + width="80.000000" /> <text - x="650" + id="text1667" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="180" - style="text-anchor:middle" - id="text1667">Users</text> + x="650">Users</text> <line - id="line1669" - stroke="black" - stroke-width="2" - y2="220.00000" - x2="602.00000" - y1="225.00000" + style="stroke:#000000;stroke-width:2.0000000" x1="610.00000" - style="stroke:#000000;stroke-width:2.0000000" /> - <line - id="line1671" - stroke="black" - stroke-width="2" - y2="230.00000" - x2="602.00000" y1="225.00000" + x2="602.00000" + y2="220.00000" + stroke-width="2" + stroke="black" + id="line1669" /> + <line + style="stroke:#000000;stroke-width:2.0000000" x1="610.00000" - style="stroke:#000000;stroke-width:2.0000000" /> + y1="225.00000" + x2="602.00000" + y2="230.00000" + stroke-width="2" + stroke="black" + id="line1671" /> <path - d="M 570.00000,175.00000 C 583.33333,175.00000 590.00000,183.33333 590.00000,200.00000 C 590.00000,220.00000 596.66667,228.33333 610.00000,225.00000" + id="path1673" style="fill:none;stroke:#000000;stroke-width:2.0000000" - id="path1673" /> + d="M 570.00000,175.00000 C 583.33333,175.00000 590.00000,183.33333 590.00000,200.00000 C 590.00000,220.00000 596.66667,228.33333 610.00000,225.00000" /> <rect - width="80.000000" - height="30.000000" - x="610.00000" - y="210.00000" + id="rect1675" style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" - id="rect1675" /> + y="210.00000" + x="610.00000" + height="30.000000" + width="80.000000" /> <text - x="650" + id="text1677" + style="line-height:0%;text-anchor:middle;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;" y="230" - style="text-anchor:middle" - id="text1677">Users</text> + x="650">Users</text> </svg> diff --git a/general-concepts/mirrors/text.xml b/general-concepts/mirrors/text.xml index 7a804d9..f380d45 100644 --- a/general-concepts/mirrors/text.xml +++ b/general-concepts/mirrors/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/mirrors/"> <chapter> <title>Mirrors</title> @@ -9,8 +9,10 @@ <body> <p> Packages will automatically have their <c>SRC_URI</c> components mirrored onto -Gentoo mirrors. When fetching, Portage checks Gentoo mirrors first before -trying the original upstream location. +Gentoo mirrors, including those hosted on the official Gentoo +Infrastructure (i.e. developer space at <c>dev.gentoo.org</c>). When +fetching, package manager checks +Gentoo mirrors first before trying the original upstream location. </p> <p> @@ -27,22 +29,22 @@ Three <c>RESTRICT</c> keywords can be used to control the mirroring process. </p> <p> -The <c>RESTRICT="mirror"</c> setting should be used if we cannot legally mirror +The <c>RESTRICT="mirror"</c> setting should be used if we cannot legally mirror certain files; files will still be downloaded from the original locations. </p> <p> The <c>RESTRICT="primaryuri"</c> setting causes Portage to try -original locations <e>first</e>, and then fall back to mirrors if necessary <d/> this -is sometimes useful if approximate download counts are needed, or if upstream -have a reliable mirror setup. +original locations <e>first</e>, and then fall back to mirrors if necessary. +This should not be used in new ebuilds. </p> <p> There is also <c>RESTRICT="fetch"</c>, which prevents Portage from trying to -fetch anything manually. The <uri link="::ebuild-writing/functions/pkg_nofetch"> -pkg_nofetch</uri> function will be called if any <c>SRC_URI</c> components cannot be -found. This should only be used if a license requires it. +fetch anything manually. +The <uri link="::ebuild-writing/functions/pkg_nofetch/">pkg_nofetch</uri> +function will be called if any <c>SRC_URI</c> components cannot be found. +This should only be used if a license requires it. </p> </body> </subsection> @@ -51,22 +53,30 @@ found. This should only be used if a license requires it. <title>Replacing Automatically Mirrored Files</title> <body> <p> -On rare occasions you may need to replace a file that is already mirrored. In this case proceed as -follows: -<ol> - <li>Put a copy of the new distfile on dev.gentoo.org into /space/distfiles-local</li> - <li>commit the new manifest to CVS</li> - <li>wait</li> -</ol> -After a few hours a cron job on dev.gentoo.org will fetch the file and replace the version on the -mirrors. The file will be automatically removed from /space/distfiles-local after approximately two -weeks. +On rare occasions you may need to replace a file that is already mirrored. +This is usually the case when upstream remakes a release package. If this +is necessary, please use <c>SRC_URI</c> arrow to rename the file. For example: +</p> + +<codesample lang="ebuild"> +# upstream updated the distfile in place, so suffix it with _YYYYMMDD +SRC_URI="https://example.com/badupstream/${P}.tar.gz -> ${P}_20191016.tar.gz" +</codesample> + +<p> +Since Gentoo mirrors operate using local distfile names, they will automatically +fetch and start distributing the new version. +</p> + +<p> +Updating an existing distfile is generally cause for concern and must be done +with care, see <uri link="::general-concepts/manifest/#Updating Manifests"/>. </p> <p> More general information about the internals of mirroring can be found on <uri -link="http://www.gentoo.org/proj/en/infrastructure/mirrors/overview-distfile.xml">infrastructure's -pages</uri>. +link="https://wiki.gentoo.org/wiki/Project:Infrastructure/Mirrors/Distfile_Mirroring_System"> +Infrastructure project's Distfile Mirroring System page</uri>. </p> </body> </subsection> @@ -76,54 +86,66 @@ pages</uri>. <title>Suitable Download Hosts</title> <body> <p> -If you have to host a source file (patch or tarball) yourself, as long as it is suitable to be -distributed by Gentoo Foundation (by license and legality), you're suggested to use your developer's -space at <c>dev.gentoo.org</c>. Since external overlays may depend on your patches/tarballs, using the -dev space at <c>dev.gentoo.org</c> keeps the distfiles at a stable and reliable infrastructure. If you -retire, other developers can take over your distfiles and place them into their own devspace. +If you have to host a source file (patch or tarball) yourself, as long as it +can be freely distributed (by license and legality), you're suggested to use +your developer's space at <c>dev.gentoo.org</c>. Since external overlays may +depend on your patches/tarballs, using the dev space at <c>dev.gentoo.org</c> +keeps the distfiles at a stable and reliable infrastructure. If you retire, +other developers can take over your distfiles and place them into their own +devspace. </p> <p> -Previous policy was to use <c>mirror://gentoo</c> directly, but this is now deprecated, as that -wouldn't allow to have long-term availability and traceability of the source files, which might be a -requirement of the license. +Previous policy was to use <c>mirror://gentoo</c> directly, but this is now +prohibited, as that wouldn't allow to have long-term availability and +traceability of the source files, which might be a requirement of the license. </p> <p> -When you upload the file to <c>dev.gentoo.org:~/public_html</c>, you must ensure that it, and its -parent directories, are world-readable. +When you upload the distfile to <c>dev.gentoo.org:~/public_html</c>, ensure that +your file and its parent directories have the correct permissions, so they're +accessible. An example <c>SRC_URI</c> referencing a distfile mirrored this way +is as follows: </p> -</body> -</subsection> -</section> -<section> -<title>Gentoo Mirrors</title> +<codesample lang="ebuild"> +SRC_URI="https://dev.gentoo.org/~myname/distfiles/${P}.tar.gz" +</codesample> -<body> <p> -To manually upload a file to <c>mirror://gentoo</c>, <c>scp</c> it to -<c>dev.gentoo.org:/space/distfiles-local</c>. You must ensure that the permissions -are set to <c>ug+rw</c> manually. The file should appear on the mirrors within four -hours (note that this is <e>less frequent</e> than -<uri link="::general-concepts/cvs-to-rsync"/>). +where <c>myname</c> refers to the username of the developer. +</p> +<p> If the upstream download location for a package uses a non-standard TCP port -(anything other than 21, 80 or 443), you <e>must</e> manually mirror the files. Not -doing so can cause all kinds of problems with strict firewalls. +(anything other than 21, 80 or 443), you <e>must</e> manually mirror the files. +Not doing so can cause all kinds of problems with strict firewalls. </p> + </body> +</subsection> </section> <section> <title>Mirroring Process</title> <body> -<figure short="Mirroring Process" link="diagram.png"> -Diagram showing the mirroring process. -</figure> +<figure short="Mirroring Process" link="diagram.png" + caption="Diagram showing the mirroring process." /> </body> </section> +<section> + <title>Third-party mirrors</title> + <body> + <p> + Usage of third-party mirrors and the <c>mirror://</c> + pseudo-protocol is described in the + <uri link="::ebuild-writing/variables/#Third-party mirrors"><c>SRC_URI</c> + variable documentation</uri>. + </p> + </body> +</section> + </chapter> </guide> diff --git a/general-concepts/news/text.xml b/general-concepts/news/text.xml index de476a6..3ff5c32 100644 --- a/general-concepts/news/text.xml +++ b/general-concepts/news/text.xml @@ -1,18 +1,20 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/news/"> <chapter> <title>News Items</title> <body> <p> -Gentoo News Items were created to provide a communication medium to push critical -messages to users via the rsync tree. The original proposal for news items is outlined -in <uri link="https://wiki.gentoo.org/wiki/GLEP:42">GLEP 42: Critical News Reporting.</uri> +Gentoo News Items were created to provide a communication medium to push +critical messages to users via the rsync tree. The original proposal for news +items is outlined in <uri link="https://www.gentoo.org/glep/glep-0042.html"> +GLEP 42: Critical News Reporting.</uri> </p> <p> -News Items can be read using the eselect command. More information on use of this tool to -read or delete news items can be found on the news.eselect man page. +News Items can be read using the eselect command. More information on use +of this tool to read or delete news items can be found on the news.eselect +man page. </p> </body> @@ -20,19 +22,40 @@ read or delete news items can be found on the news.eselect man page. <title>Adding a news item</title> <body> -<p> <ul> - <li>Choose a file name in the proper format: YYYY-MM-DD-name.lang.txt, where the date is followed by a name (a-z, 0-9, + (plus), - (hyphen) and _ (underscore)), the two-letter ISO language code (en for English must be chosen as default) and the file extension txt.</li> - <li>Write the news item, which is similar to a RFC-compliant email. Details concerning what is allowed can be found in the appropriate GLEP section. As a note: Exceptions depending on installed packages or activated profiles is possible.</li> - <li>Send the news item to the gentoo-dev mailing list and the Gentoo PR team (pr@gentoo.org) 72 hours in advance of commit.</li> - <li>Wait for corrections or feedback that your news item is not of great importance and should be revoked (can be possible).</li> - <li>Upon acceptance, create a detached armored GnuPG signature with gpg --local-user --detach-sign --armor YYYY-MM-DD-name.lang.txt</li> - <li>Verify that your signature is correct with gpg --verify YYYY-MM-DD-name.lang.txt.asc YYYY-MM-DD-name.lang.txt</li> - <li>Create a directory structure for your item in the gentoo-news repository (<c>git+ssh://git@git.gentoo.org/proj/gentoo-news.git</c>): YYYY/YYYY-MM-DD-name/.</li> - <li>Add both the news file and the signature to that directory.</li> - <li>Commit and push your changes to the gentoo-news repository.</li> + <li> + Choose a filename in the proper format: + <c>YYYY-MM-DD-shortname.lang.txt</c>, i.e. the date, followed by a very + short name of at most 20 characters and consisting only of <c>a-z</c>, + <c>0-9</c>, <c>+</c> (plus), <c>-</c> (hyphen) and <c>_</c> (underscore). + This is followed by <c>lang</c> which is an + <uri link="https://tools.ietf.org/rfc/bcp/bcp47.txt">IETF language + tag</uri>. Always use <c>en</c> for English, unless you are translating + a news item. Finally, the filename ends with the extension <c>txt</c>. + </li> + <li> + Write the news item, which is similar to a RFC-compliant email. Details + concerning what is allowed can be found in the appropriate GLEP section. + As a note: Exceptions depending on installed packages or activated + profiles are possible. + </li> + <li> + Send the news item to the gentoo-dev mailing list and the Gentoo PR team + (pr@gentoo.org) 72 hours in advance of commit. + </li> + <li> + Wait for corrections or feedback that your news item is not of great + importance and should be revoked (can be possible). + </li> + <li> + Create a directory structure for your item in the gentoo-news repository + (<c>git+ssh://git@git.gentoo.org/data/gentoo-news.git</c>): + <c>YYYY-MM-DD-shortname/</c>. + </li> + <li>Add the news file to that directory.</li> + <li>Commit and push your changes to the gentoo-news repository.</li> </ul> -</p> + </body> </section> diff --git a/general-concepts/overlay/text.xml b/general-concepts/overlay/text.xml index e2c773c..72463e9 100644 --- a/general-concepts/overlay/text.xml +++ b/general-concepts/overlay/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/overlay/"> <chapter> <title>Overlay</title> @@ -6,8 +6,8 @@ <body> <p> Portage can look in multiple places for packages by using an overlay. The -locations of overlays are controlled by the <c>PORTDIR_OVERLAY</c> variable, which -should contain a space-separated list of paths. +locations of overlays are controlled by the <c>location</c> variable +in one or more repos.conf files. </p> <p> @@ -40,10 +40,10 @@ override existing entries. <p> Be very careful when using eclasses in an overlay. Portage will not do cache updates when an overlay eclass is changed, nor will it do cache updates when a -main Portage tree eclass which is used by an overlay ebuild changes. You may +main Gentoo repository eclass which is used by an overlay ebuild changes. You may also encounter bogus 'illegal inherit' notices when working with eclasses in -an overlay (see <uri -link="::appendices/common-problems/#QA Notice -- ECLASS foo inherited illegally"/>). +an overlay (see +<uri link="::appendices/common-problems/#QA Notice: ECLASS foo inherited illegally"/>). To be safe, manually <c>touch</c> all relevant overlay files after updating overlay eclasses. </p> diff --git a/general-concepts/package-collisions/text.xml b/general-concepts/package-collisions/text.xml new file mode 100644 index 0000000..66536ee --- /dev/null +++ b/general-concepts/package-collisions/text.xml @@ -0,0 +1,49 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="general-concepts/package-collisions/"> +<chapter> +<title>Package Collisions</title> +<body> + +<p> +When you encounter a package that is trying to install files that are +already provided by another package (detectable with +<c>FEATURES=collision-protect</c> for example) you have to fix this +situation before you can commit the ebuild or, if you encounter this +with an existing package, file a bug about that package (see below for +a few exceptions). The reason file conflicts are critical is because +if "foo" provides the file <c>/usr/bin/example</c> and "bar" is +going to overwrite it, and later "bar" is unmerged, Portage will remove +<c>/usr/bin/example</c> and it is therefore likely it will break +"foo". +</p> + +<p> +The most obvious fix is to add a blocking dependency to both packages +that want to install that file, so they can't be installed at the same +time. But unless there are also other reasons for those packages to +block each other you should avoid this if possible and rather fix the +package, which could include one or more of the following steps: +</p> + +<ul> + <li>Make "foo" (R)DEPEND on "bar" and not install the conflicting + file.</li> + <li>Remove conflicting files from "foo" in <c>src_install</c> + or <c>pkg_preinst</c>.</li> + <li>Move conflicting files into a new subpackage and make "foo" and + "bar" both (R)DEPEND on that package.</li> + <li>Change the location where "foo" or "bar" installs conflicting + files.</li> +</ul> + +<p> +In some cases conflicting files can't be really fixed or aren't +critical, currently known exceptions are Perl module manpages +(overwriting the ones from Perl itself) and <c>CONFIG_PROTECT</c>'ed +files (which should still be fixed, but aren't critical as Portage +won't overwrite them). +</p> + +</body> +</chapter> +</guide> diff --git a/general-concepts/package-maintainers/text.xml b/general-concepts/package-maintainers/text.xml new file mode 100644 index 0000000..6d37795 --- /dev/null +++ b/general-concepts/package-maintainers/text.xml @@ -0,0 +1,92 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="general-concepts/package-maintainers/"> +<chapter> +<title>Package Maintainers</title> +<body> + +<p> +Package maintainers are responsible for ebuild maintenance tasks <d/> +bumping ebuilds to new upstream releases, updating them as necessary +with regards to policies, replying to bugs, etc. The maintainers +of a package are listed in the package's <uri +link="::ebuild-writing/misc-files/metadata/">metadata.xml</uri> file. +When assigning bugs, the first maintainer listed becomes the bug's +assignee and the remaining maintainers are added to CC, unless stated +otherwise in the metadata. +</p> +</body> + +<section> +<title>Maintainer authority</title> +<body> + +<p> +Package maintainers have authority over their maintained packages. +Unless specified otherwise, you should request maintainers' approval +before committing to their packages. Try filing a bug, catching them +on IRC or sending a mail first. The exceptions to this rule are trivial +changes implied by your own actions, e.g. dependency updates as a result +of package moves. +</p> + +<p> +In case of maintainer inactivity, it is a good idea to consult other +developers on how to handle the situation, especially if it is +a critical issue that needs to be handled ASAP. A customary tool +of maintainer timeout may be used in this case. This timeout can be +invoked if none of the package's maintainers reply to a patch within +2<d/>4 weeks of it being attached or linked to a correctly assigned bug, +or being sent to the maintainer. +</p> + +<important> +Common sense dictates to us that toolchain/base-system/core packages +and eclasses or anything else which is delicate (e.g. glibc) or widely +used (e.g. GTK+) should usually be left to their maintainers. +If in doubt, don't touch it. +</important> + +<p> +Respect developers' coding preferences. Unnecessarily changing +the syntax of an ebuild can cause complications for others. Syntax +changes should only be done if there is a real benefit, such as faster +compilation, improved information for the end user, or compliance +with Gentoo policies. +</p> + +</body> +</section> + +<section> +<title>Adding and removing maintainers</title> +<body> + +<p> +All packages newly added to the Gentoo repository must have at least +one maintainer specified. New maintainers can only be added with their +consent. In particular, it is not acceptable to add generic projects +(such as the Python project) as package maintainers without the approval +of their members or against their explicit policy. +</p> + +<p> +Maintainers without commit access are called proxied maintainers. Their +changes must be pushed by a Gentoo developer, who acts as their proxy. +All packages maintained by proxied maintainers must explicitly list +their proxy developer or project in <c>metadata.xml</c>. +</p> + +<p> +When adding new maintainers or removing old maintainers, please remember +to reassign bugs. The last maintainer to resign from maintaining +the package must place a <c><!-- maintainer-needed --></c> comment +in <c>metadata.xml</c>, in order simplify finding unmaintained packages. +It is also required to send an 'up for grabs' email to the +<c>gentoo-dev-announce</c> and <c>gentoo-dev</c> mailing lists, +providing a list of newly-unmaintained packages. +</p> + +</body> +</section> +</chapter> +</guide> diff --git a/general-concepts/pic/text.xml b/general-concepts/pic/text.xml index 4c0613c..8d6cfff 100644 --- a/general-concepts/pic/text.xml +++ b/general-concepts/pic/text.xml @@ -1,15 +1,25 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/pic/"> <chapter> <title>Position Independent Code</title> - <body> + <p> -On some architectures, shared libraries must be built with -fPIC. On x86 and others, shared libraries may build without -fPIC. This can be wasteful and potentially cause a performance hit. +On some architectures, shared libraries must be built with <c>-fPIC</c>. +On <c>x86</c> and others, shared libraries may build without <c>-fPIC</c>. +This can be wasteful and potentially cause a performance hit. </p> -<p>If you encounter a package that is not building shared libraries with -fPIC, patch the Makefile to build only the shared libraries with -fPIC. More information on PIC is available at the <uri link="https://wiki.gentoo.org/wiki/Project:Hardened/Position_Independent_Code_internals">PIC internals</uri> wiki page. If you are unsure, please ask in a public developer forum (like the gentoo-dev mailing list or #gentoo-dev irc channel) for help. + +<p> +If you encounter a package that is not building shared libraries with +<c>-fPIC</c>, patch the Makefile to build only the shared libraries with +<c>-fPIC</c>. More information on PIC is available at the +<uri link="https://wiki.gentoo.org/wiki/Project:Hardened/Position_Independent_Code_internals"> +PIC internals</uri> wiki page. If you are unsure, please ask in a public +developer forum (like the <c>gentoo-dev</c> mailing list or the +<c>#gentoo-dev</c> IRC channel) for help. </p> -</body> +</body> </chapter> </guide> diff --git a/general-concepts/portage-cache/text.xml b/general-concepts/portage-cache/text.xml index f185f62..96fea32 100644 --- a/general-concepts/portage-cache/text.xml +++ b/general-concepts/portage-cache/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/portage-cache/"> <chapter> <title>The Portage Cache</title> @@ -12,38 +12,43 @@ these variables must be either static or generated using only unchanging </p> <p> +The cache, when generated, must be identical independent of the used machine +or environment. This concept is referred to as <e>metadata invariance</e>. +</p> + +<p> So, the following will not work: </p> <codesample lang="ebuild"> # DO NOT DO THIS! if ! has_version "x11-libs/gtk+" ; then - DEPEND="${DEPEND} - gtk? ( >=x11-libs/gtk+-2 ) - !gtk? ( =x11-libs/gtk+-1.2* )" + DEPEND="${DEPEND} + gtk? ( >=x11-libs/gtk+-2 ) + !gtk? ( =x11-libs/gtk+-1.2* )" fi </codesample> <p> -However, this is legal, since <c>versionator.eclass</c> works upon <c>PV</c>, and -<c>PV</c> and <c>PN</c> are both static: +However, the following is legal, since <c>eapi7-ver.eclass</c> works upon +<c>PV</c>, <c>PV</c>, and <c>PN</c> are both static: </p> <codesample lang="ebuild"> -inherit versionator +inherit eapi7-ver -if [[ $(get_major_version) -ge 7 ]] ; then - IUSE="${IUSE} tcltk mzscheme" - DEPEND="${DEPEND} - tcltk? ( dev-lang/tcl ) - mzscheme? ( dev-lisp/mzscheme )" - RDEPEND="${RDEPEND} - tcltk? ( dev-lang/tcl ) - mzscheme? ( dev-lisp/mzscheme )" +if ver_test -ge 7.0 ; then + IUSE="${IUSE} tcltk mzscheme" + DEPEND="${DEPEND} + tcltk? ( dev-lang/tcl ) + mzscheme? ( dev-lisp/mzscheme )" + RDEPEND="${RDEPEND} + tcltk? ( dev-lang/tcl ) + mzscheme? ( dev-lisp/mzscheme )" - if [[ "${MY_PN}" != "vim-core" ]] ; then - RDEPEND="${RDEPEND} !<app-vim/align-30-r1" - fi + if [[ "${MY_PN}" != "vim-core" ]] ; then + RDEPEND="${RDEPEND} !<app-vim/align-30-r1" + fi fi </codesample> </body> @@ -60,17 +65,22 @@ solely upon <c>PN</c> are allowed. <p> As an example of a legal and possibly useful conditional inherit, some eclasses -do: +or ebuilds do: </p> <codesample lang="ebuild"> -if [[ "${PN##*-}" == "cvs" ]] ; then - inherit cvs +if [[ ${PV} == 9999 ]]; then + inherit git-r3 + EGIT_REPO_URI="https://anongit.gentoo.org/git/proj/devmanual.git" +else + SRC_URI="https://dev.gentoo.org/~ulm/distfiles/${P}.tar.xz" + KEYWORDS="~amd64 ~arm ~hppa ~ppc ~ppc64 ~sparc ~x86" fi </codesample> <p> -This allows the same eclass to be used for both regular and <c>-cvs</c> packages. +This allows the same eclass (or the same ebuild "template") to be used for both +regular and live packages. </p> </body> </section> diff --git a/general-concepts/privileges/text.xml b/general-concepts/privileges/text.xml deleted file mode 100644 index 8dc516b..0000000 --- a/general-concepts/privileges/text.xml +++ /dev/null @@ -1,15 +0,0 @@ -<?xml version="1.0"?> -<guide self="general-concepts/privileges/"> -<chapter> -<title>Privileges</title> - -<body> -<todo> -general privs stuff, include stuff on setuid/setgid and sticky since -a lot of people seem to be confused about those... Also notes on the portage -user and group issues, and what we use for root:root to make *bsd work. -</todo> -</body> - -</chapter> -</guide> diff --git a/general-concepts/projects/text.xml b/general-concepts/projects/text.xml new file mode 100644 index 0000000..19188d4 --- /dev/null +++ b/general-concepts/projects/text.xml @@ -0,0 +1,96 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="general-concepts/projects/"> +<chapter> +<title>Projects</title> +<body> + +<p> +The management structure of Gentoo, called the "metastructure", is +defined in +<uri link="https://www.gentoo.org/glep/glep-0039.html#specification"> +GLEP 39</uri>. In Gentoo, a project is a group of developers working +towards a common goal in various different areas. For example, the +<uri link="https://wiki.gentoo.org/wiki/Project:Devmanual"> +Devmanual</uri> project focuses on maintaining this document. Many +others are responsible for maintaining packages. Projects spanning a +large area of topics can have multiple subprojects specializing in +particular fields within the domain of the parent project and thus +form a project hierarchy. +</p> + +<p> +A package maintained by a project needs to have the +project explicitly listed as a maintainer in its +<uri link="::ebuild-writing/misc-files/metadata/">metadata.xml</uri>. +The full listing of all the projects can be found on +<uri link="https://api.gentoo.org/metastructure/projects.xml"> +api.gentoo.org</uri> or on the +<uri link="https://wiki.gentoo.org/wiki/Project:Gentoo">wiki</uri>. +</p> +</body> + +<section> +<title>Starting New Projects</title> +<body> + +<p> +According to the metastructure any developer may create a new +project. There are two procedures involved in starting a new project: +</p> + +<ol> + <li> + Create a new project page <uri + link="https://wiki.gentoo.org/wiki/Gentoo_Wiki:Developer_Central/Project_pages"> + through the wiki</uri>. + </li> + <li> + Post a Request For Comments (RFC) email to the gentoo-dev + mailing list. + </li> +</ol> + +<p> +There is no approval required for the RFC and negative comments do not +block a developer from creating a project. Competing projects are +allowed to co-exist in Gentoo; existence of another project with +similar goals do not block another developer from starting a new +project with the same goals. +</p> + +</body> +</section> + +<section> +<title>Joining and Leaving a Project</title> +<body> + +<p> +Members of a project are managed through the project's page on the +Gentoo Wiki. Each page has a "Project" template in its source which +lists the members of the project. Simply modifying the list is +sufficient for adding or removing a developer. Note that different +projects have different requirements and procedures for recruiting +developers, which may require prior arrangements to be made before +modifying the member list. It is standard however to consult +the project lead. +</p> + +<p> +If the project has an official IRC channel listed on its project page, +developers should join the channel if possible to facilitate +coordination and collaboration. +</p> + +<p> +Developers should remember to add themselves to the alias by editing +<c>/var/mail/alias/misc/<alias name></c> on +dev.gentoo.org. For example, the alias for the Devmanual project is +located at <c>/var/mail/alias/misc/devmanual</c>, which corresponds to +the project's email address <c>devmanual@gentoo.org</c>. +</p> + +</body> +</section> +</chapter> +</guide> diff --git a/general-concepts/sandbox/text.xml b/general-concepts/sandbox/text.xml index 8fd63a4..8dcaeb1 100644 --- a/general-concepts/sandbox/text.xml +++ b/general-concepts/sandbox/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/sandbox/"> <chapter> <title>Sandbox</title> diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml index 96aa4fc..9eabf08 100644 --- a/general-concepts/slotting/text.xml +++ b/general-concepts/slotting/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/slotting/"> <chapter> <title>Slotting</title> @@ -12,11 +12,15 @@ parallel. This feature is called slotting. </p> <p> -Most packages have no need for slotting. These packages specify <c>SLOT="0"</c> in -the ebuilds. This is <b>not</b> the same as specifying an empty slot <d/> an empty -slot means "disable slotting entirely", and should not be used. +Most packages have no need for slotting. These packages specify <c>SLOT="0"</c> +in the ebuilds. This is purely a convention; the package manager does not treat +<c>0</c> any different from other slot values. </p> +<note> +<c>SLOT</c> is a mandatory variable and must not be empty. +</note> + <p> Portage permits at most one instance of a package installation <e>per <c>SLOT</c> value</e>. For example, say we have the following: @@ -37,7 +41,7 @@ possible that the user may have <c>foo-2.0</c> installed and no <c>foo-1.x</c> a <p> To <c>DEPEND</c> upon a package in a specific slot, refer to -<uri link="::general-concepts/dependencies#SLOT Dependencies" />. +<uri link="::general-concepts/dependencies/#SLOT Dependencies"/>. </p> </body> @@ -51,14 +55,115 @@ but it's undesirable or inconvenient to allow some of these versions to be insta simultaneously. In <c>EAPI=5</c> and higher, this situation can be handled by using sub-slots, which are delimited from the regular slot by a <c>/</c> character, as in <c>SLOT="slot/subslot"</c>. Packages can -<uri link="::general-concepts/dependencies#Slot Operators">request to be +<uri link="::general-concepts/dependencies/#Slot Operators">request to be automatically rebuilt</uri> when the subslot of a runtime dependency changes. </p> <p> -For example, suppose package <c>foo</c> installs a library whose soname is -different for different versions. It would be reasonable to use the soname version -as the sub-slot name: +If an ebuild does not explicitly declare a sub-slot, the regular slot is used +as the value of the sub-slot by default. +</p> + +<p> +You may wish to review the +<uri link="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Subslots"> +QA team's documentation on subslots</uri>. +</p> + +<note> +Care must be taken when using sub-slots in a library ebuild for the first time. +Adding sub-slots will trigger rebuilds for all the packages that already use +slot-operator dependencies (e.g. switching from SLOT="0" to SLOT="0/14" in +<c>media-libs/libpng</c> and package <c>foo</c> depends on <c>libpng:0=</c>). +Therefore, it's best if you start using sub-slots in the library when the +existing library interface changes. +</note> +</body> + +<subsection> +<title>ABI breakage</title> +<body> + +<p> +There are two ways a library can break compatibility with its consumers. +</p> + +<dl> + <dd> + ABI (Application Binary Interface): this affects binaries built before the + change. Applications linked against a library pre-ABI break may not work + correctly after the break. These changes are related to internal structure, + such as the size of a <c>struct</c> or the type of an argument (e.g. + integer width). Fixing this requires a <e>rebuild</e> of all consumers. + </dd> + <dd> + API (Application Programming Interface): this affects consumers at compile + time and usually occurs when a library has deprecated and then removed a + function. Fixing this requires a <e>code change</e> in consumers. + </dd> +</dl> + +<p> +Note that subslots are not used exclusively for this purpose. While they form +the majority of uses in the Gentoo tree, subslots may have a meaning that +is completely divorced from SONAMEs or ABI breakage. Check the usage in the +relevant packages before using a subslot operator! +</p> + +<p> +When made aware of ABI breakage, change the subslot. Note that the subslot does +not have to strictly be the SONAME and therefore could be an arbitrary string +(following naming rules). +</p> + +<p> +Be aware that some upstreams may make releases without verifying if binary +compatibility has been broken in a minor release. You should check using +tools like <c>dev-util/libabigail</c> or <e>ABI Laboratory</e> (available +in Gentoo as <c>dev-util/abi-compliance-checker</c> if you prefer the non-web +version). +</p> + +<p> +Generally, consumers <e>which link against</e> a library possessing a subslot +that <e>represents SONAME or binary compatibility</e> should subscribe to +it (request to be rebuilt when the subslot changes) with <c>:=</c>. Also, see +the QA Policy Guide for information on +<uri link="https://projects.gentoo.org/qa/policy-guide/dependencies.html#proactive-use-of-slot-operators"> +proactively subscribing to subslots</uri> before they are defined. +</p> +</body> + +<subsubsection> +<title>General naming of a sub-slot</title> +<body> + +<p> +As a simple rule of thumb, the SONAME is usually a function of the library's +linking filename <c>libfoo.so</c> and its <b>first version component</b>. +The remaining version components are useful for ensuring a monotonic upgrade +path of consumers, but aren't incorporated into the library's SONAME, which in +this case would be <c>libfoo.so.1</c>. +</p> + +<p> +The SONAME being incremented implies that the library's ABI has been broken. +</p> + +<p> +As a result of the aforementioned convention, ebuilds usually expose the current +ABI version as the subslot. For this <e>libfoo</e> example, if the library is +<c>libfoo.so.1.2</c>, the ebuild might set: +</p> + +<codesample lang="ebuild"> +SLOT="0/1" +</codesample> + +<p> +Further, suppose the package <c>foo</c> installs a library whose SONAME is +different for different versions. It would be reasonable to use the SONAME +version as the sub-slot name: </p> <ul> @@ -74,22 +179,41 @@ can then request to be automatically rebuilt when the installed version of <c>foo:2</c> or <c>foo:1</c> changes sub-slots <d/> for example, when the user upgrades from <c>foo-2.0</c> to <c>foo-2.1</c>. </p> +</body> +</subsubsection> + +<subsubsection> +<title>Multiple libraries within a single package</title> +<body> <p> -If an ebuild does not explicitly declare a sub-slot, the regular slot is used -as the value of the sub-slot by default. +A package might need to install several libraries. The canonical example +of this is <c>media-video/ffmpeg</c>: </p> -<note> -Care must be taken when using sub-slots in a library ebuild for the first time. -Adding sub-slots will trigger rebuilds for all the packages that already use sub-slot -dependencies (e.g. Switching from SLOT="0" to SLOT="0/14" in <c>media-libs/libpng</c> and -package <c>foo</c> depends on <c>libpng:0=</c>). -Therefore, it's best if you start using sub-slots in the library when the existing library -interface changes. -</note> +<codesample lang="ebuild"> +# Subslot: <libavutil_major>.<libavcodec_major>.<libavformat_major> +# Since FFmpeg ships several libraries, subslot is kind of limited here. +# Most consumers will use those three libraries, if a "less used" library +# changes its soname, consumers will have to be rebuilt the old way +# (preserve-libs) - which should not be relied upon. +# If, for example, a package does not link to libavformat and only libavformat +# changes its ABI then this package will be rebuilt needlessly. Hence, such a +# package is free _not_ to := depend on FFmpeg but I would strongly encourage +# doing so since such a case is unlikely. +SLOT="0/56.58.58" +</codesample> + +<p> +In such cases, make the subslot a composite of the major SONAMEs of each of +the installed libraries. This emphasises a point made above <d/> subslots do +not need to be equal to the exact SONAME of installed libraries, they only need +to represent in some way ABI compatibility. +</p> </body> +</subsubsection> +</subsection> </section> <section> @@ -97,9 +221,9 @@ interface changes. <body> <p> -Current versions of portage accept slot and sub-slot names that begin with an -alphanumeric character or <c>'_'</c>, and contain alphanumerics and <c>'_'</c>, -<c>'-'</c>, <c>'.'</c>, and <c>'+'</c> characters. +Current versions of Portage accept slot and sub-slot names that begin with an +alphanumeric character or <c>_</c>, and contain alphanumerics and <c>_</c>, +<c>-</c>, <c>.</c>, and <c>+</c> characters. </p> </body> diff --git a/general-concepts/text.xml b/general-concepts/text.xml index 108fe00..c10d1fd 100644 --- a/general-concepts/text.xml +++ b/general-concepts/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/"> <chapter> <title>General Concepts</title> @@ -6,7 +6,7 @@ <body> <p> This section covers some general concepts with which you should be familiar when -writing ebuilds or working with the Portage tree. +writing ebuilds or working with the Gentoo repository. </p> </body> @@ -19,26 +19,27 @@ writing ebuilds or working with the Portage tree. </chapter> +<!-- Keep in alphabetical order --> <include href="autotools/"/> <include href="config-protect/"/> -<include href="cvs-to-rsync/"/> +<include href="copyright-policy/"/> <include href="dependencies/"/> -<include href="manifest/"/> -<include href="distributed-building/"/> <include href="ebuild-revisions/"/> <include href="emerge-and-ebuild/"/> -<include href="features/"/> <include href="filesystem/"/> -<include href="herds-and-projects/"/> +<include href="git-to-rsync/"/> <include href="install-destinations/"/> <include href="licenses/"/> -<include href="linguas/"/> +<include href="mailing-lists/"/> +<include href="manifest/"/> <include href="mirrors/"/> <include href="news/"/> <include href="overlay/"/> +<include href="package-collisions/"/> +<include href="package-maintainers/"/> <include href="pic/"/> <include href="portage-cache/"/> -<include href="privileges/"/> +<include href="projects/"/> <include href="sandbox/"/> <include href="slotting/"/> <include href="tree/"/> diff --git a/general-concepts/tree/text.xml b/general-concepts/tree/text.xml index 2bceca5..9fb9cb9 100644 --- a/general-concepts/tree/text.xml +++ b/general-concepts/tree/text.xml @@ -1,11 +1,11 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/tree/"> <chapter> -<title>The Portage Tree</title> +<title>The Gentoo Repository</title> <body> <p> -The basic layout of the portage tree is as follows: +The basic layout of the Gentoo repository is as follows: </p> <ul> @@ -17,7 +17,6 @@ The basic layout of the portage tree is as follows: Package directories for example <c>app-editors/vim</c> <ul> <li>Package metadata, for example <c>app-editors/vim/metadata.xml</c></li> - <li>Package changelog, for example <c>app-editors/vim/ChangeLog</c></li> <li>Package Manifest, for example <c>app-editors/vim/Manifest</c></li> <li> Ebuilds, for example <c>app-editors/vim/vim-6.3.068.ebuild</c>, @@ -39,6 +38,26 @@ The basic layout of the portage tree is as follows: <li>Eclasses directory, <c>eclass/</c></li> <li>Licenses directory, <c>licenses/</c></li> <li> + Metadata directory, <c>metadata/</c>. Most of the listed contents + are not kept directly in the main git tree but instead + auto-generated or included from other repositories as part of the + <uri link="::general-concepts/git-to-rsync/">Git to Rsync</uri> + process. + <ul> + <li> + Various control files, for example <c>layout.conf</c>, <c>timestamp</c> + and <c>projects.xml</c>. Only <c>layout.conf</c> exists in the main git tree. + </li> + <li> + XML validation files in <c>metadata/dtd/</c> and <c>metadata/xml-schema/</c>. + </li> + <li> + Security advisories in <c>metadata/glsa/</c> and news items in + <c>metadata/news/</c> + </li> + </ul> + </li> + <li> Profiles directory, <c>profiles/</c> <ul> <li> @@ -57,14 +76,6 @@ The basic layout of the portage tree is as follows: </ul> </li> <li>Scripts directory, <c>scripts/</c></li> - <li> - Distfiles directory, <c>distfiles/</c>. This is not included in the main - CVS tree, but it will be found on most user systems. - </li> - <li> - Packages directory, <c>packages</c>. Again, this is found on user systems but not - in the main CVS tree. - </li> </ul> </body> @@ -80,97 +91,92 @@ Things that do <b>not</b> belong in the tree: <li>Large patches</li> <li>Non-text files</li> <li>Photos of teletubbies</li> - <li>Files whose name starts with a dot</li> + <li>Files whose name contains characters outside <c>[A-Za-z0-9._+-]</c></li> + <li>Files whose name starts with a dot, a hyphen, or a plus sign</li> </ul> <p> +Naming rules for distfiles are more lenient, but for interoperability their +filenames are restricted to the printable ASCII range excluding SPACE, i.e., +U+0021 to U+007E (see also +<uri link="https://www.gentoo.org/glep/glep-0031.html#suitable-characters-for-file-and-directory-names"> +GLEP 31</uri>). Any characters that have a special meaning in Bash or in +<c>SRC_URI</c> should also be avoided. If necessary, upstream files can be +<uri link="::ebuild-writing/variables/#Renaming Sources">renamed</uri> using +<c>-></c> syntax. +</p> + +<p> Software-wise, in general all of the following should be met in order for a package to be included in the tree: </p> <dl> <dt>Active, Cooperative Upstream</dt> <dd> - <p> If a package is undeveloped or unmaintained upstream, it can be extremely difficult to get problems fixed. If a package does not have an active upstream, the developers who add the package to the tree must ensure that they are able to fix any issues which may arise. - </p> - <p> +</dd> +<dd> Sometimes upstream may have a reason for not wanting their package included in the tree. This should be respected. - </p> </dd> <dt>Reasonably Stable</dt> <dd> - <p> Keep super-experimental things out of the tree. If you must commit them, consider using <c>package.mask</c> until things calm down, or better yet make them available as overlay ebuilds. - </p> </dd> <dt>Reasonably Useful</dt> <dd> - <p> Don't feel obliged to include "Joe's '1337 XMMS Skinz Collection" or "Hans' Super Cool Fast File System" in the tree just because a few users ask for it. Stick to things that might actually be of use. - </p> </dd> <dt>Properly Packaged</dt> <dd> - <p> If something is only available in live CVS or dodgy autopackage format, don't include it until upstream can come up with a decent source package. Similarly, avoid things that don't have a proper build system (where relevant) <d/> these are very tricky to maintain. - </p> </dd> <dt>Patching and Distribution Permitted</dt> <dd> - <p> If we can't patch packages as necessary ourselves, we end up relying entirely upon upstream for support. This can be problematic, especially if upstream are slow at fixing things. We don't want to be in the situation where we can't stable a critical package because we're still waiting for a closed-source vendor to get their act together. - </p> - - <p> +</dd> +<dd> Similarly, not being able to mirror and distribute tarballs ourselves makes us rely entirely upon upstream mirrors. Experience has shown that these are often extremely unreliable, with files changing, moving or vanishing at random. - </p> </dd> <dt>Working Ebuilds</dt> <dd> - <p> If you don't have a <e>working</e> ebuild, don't include it. - </p> </dd> <dt>Portable</dt> <dd> - <p> If software is unportable, it's generally because it's badly written. Remember that although x86 has a market majority <e>now</e>, it probably won't in the not too distant future once x86-64 catches on. - </p> </dd> <dt>Reasonable Security Record</dt> <dd> - <p> Don't include software that has a terrible security record. Each vulnerability is a <e>lot</e> of work for a lot of people (security teams, arch teams and package maintainers). - </p> </dd> </dl> diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml index f187808..5caa430 100644 --- a/general-concepts/use-flags/text.xml +++ b/general-concepts/use-flags/text.xml @@ -1,81 +1,159 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/use-flags/"> <chapter> <title>USE Flags</title> <body> <p> - <c>USE</c> flags are to control optional dependencies and settings which - the user may reasonably want to select. For example, <c>app-editors/vim</c> - can optionally build with support for the <c>ruby</c> interpreter, and it - needs <c>dev-lang/ruby</c> installed to do this <d/> we use the ruby - <c>USE</c> flag to provide this option. On the other hand, - <c>app-text/glark</c> requires <c>ruby</c> no matter what, so no <c>USE</c> - flag is used there. +<c>USE</c> flags are to control optional dependencies and settings which +the user may reasonably want to select. For example, <c>app-editors/vim</c> +can optionally build with support for the <c>ruby</c> interpreter, and it +needs <c>dev-lang/ruby</c> installed to do this <d/> we use the ruby +<c>USE</c> flag to provide this option. On the other hand, +<c>app-text/glark</c> requires <c>ruby</c> no matter what, so no <c>USE</c> +flag is used there. </p> <p> - No combination of <c>USE</c> flags should cause a package to fail to build - because users can set any combination of flags. +No combination of <c>USE</c> flags should cause a package to fail to build +because users can set any combination of flags. </p> <p> - Packages should not configure and link based upon what is available at - compile time <d/> any autodetection must be overridden. This is commonly - referred to as the dependency being "automagic" - This is bad because the - dependency is not detected by the package manager tools and can easily - break, among other issues. +Packages should not configure and link based upon what is available at +compile time <d/> any autodetection must be overridden. This is commonly +referred to as the dependency being "automagic". This is bad because the +dependency is not detected by the package manager tools and can easily +break, among other issues. </p> <p> - The usage of a <c>USE</c> flag should not control runtime dependencies when - the package does not link to it. Doing so will create extra - configuration for the package and re-compilation for no underlying file - change on disk. This should be avoided and instead can be conveyed to the - user via post install messages if needed. +Automagic dependencies are preferably fixed by preparing a build system patch +adding appropriate options to control the dependency in question, and submitting +this patch upstream for the benefit of all users. To avoid carrying additional +patches downstream, automagic dependencies can usually be worked around using +special build system options (e.g. cache variables in autotools) or through +depending on the relevant packages unconditionally (i.e. forcing the check +to always succeed). </p> <note> - The status of USE flags is saved in the VDB, and their value in - <c>pkg_prerm</c> and <c>pkg_postrm</c> is taken from there. This means that - setting or unsetting a USE flag between merge and unmerge has no effect. +The states of USE flags are saved in the VDB, and their values in +<c>pkg_prerm</c> and <c>pkg_postrm</c> are taken from there. This means that +setting or unsetting a USE flag between merge and unmerge has no effect. </note> </body> <section> +<title>When not to use USE flags?</title> +<body> +<p> +While <c>USE</c> flags are generally considered beneficial to users, there +are valid use cases for avoiding them. When writing ebuilds, consider whether +to add flags for particular conditional features, or explore one +of the alternative solutions described below. +</p> + +<p> +The usage of a <c>USE</c> flag should not control runtime dependencies when +the package does not link to it. Doing so will create extra +configuration for the package and re-compilation for no underlying file +change on disk. This should be avoided and instead can be conveyed to the +user via post install messages if needed. +</p> + +<p> +<c>USE</c> flags must not be used to control installing files that are small, +non-intrusive, do not introduce additional build-time dependencies or cause +a significant increase in build time. Examples of such files are bash completion +files, init.d scripts, logrotate configuration files, systemd service files. +The rationale is the same as above. Instead, those files must be installed +unconditionally. +</p> + +<p> +A similar case can be made for packages having multiple conditional programs +or modules. Whenever this results in a large number of <c>USE</c> flags that +would force the user to spend a lot of time choosing compatible flags +and possibly rebuilding after incomplete choices, consider reducing the use +of flags to those programs or modules that have external dependencies +and/or long build times. The rest of them should be built unconditionally +instead, or controlled by a flag such as <c>minimal</c>. +</p> + +<p> +You should not introduce USE flags that manipulate compiler flags or similar +variables configured directly by the user (e.g. <c>-O3</c>, <c>-flto</c>). +Instead, packages should avoid manipulating them at all, and let users set +them directly. Common mistakes include: +</p> + +<ol> + <li> + Using <c>debug</c> USE flag to force <c>-O0 -g</c> and disable + stripping. The correct purpose of <c>debug</c> flag is to control additional + debug code paths. The use of correct flags and features to preserve + debugging information is user's responsibility. + </li> + + <li> + Introducing <c>lto</c> flag to force <c>-flto</c>. This is something the user + should set directly in flag variables. + </li> + + <li> + Using <c>CPU_FLAGS_*</c> to control <c>-m*</c> options. Those flags are + intended to control code paths explicitly requiring specific CPU extensions, + e.g. separate assembly. Compiler-generated assembly should respect user's + <c>-march</c> choice. + </li> +</ol> + +<p> +There might be corner cases where these rules do not apply. For example, a few +upstreams require users to use specific <c>CFLAGS</c> and reject bug reports +against builds using other values. In this case, it is customary to strip flags +by default and provide <c>custom-cflags</c> flag to allow users to force their +preferred flags. Another exception are <c>CFLAGS</c> that enable/disable +features at compile time (via pre-processor macros). +</p> +</body> +</section> + +<section> <title><c>noblah</c> USE Flags</title> <body> <p> - Avoid <c>noblah</c> style <c>USE</c> flags. These break <c>use.mask</c> and - cause all sorts of complications for arch developers. Here's why: +Avoid <c>noblah</c> style <c>USE</c> flags. These break <c>use.mask</c> and +cause all sorts of complications for arch developers. Here's why: </p> <p> - Consider a hypothetical package named 'vplayer', which plays videos. This - package has optional support, via <c>USE</c> flags, for various sound and - video output methods, various video codecs and so on. +Consider a hypothetical package named 'vplayer', which plays videos. This +package has optional support, via <c>USE</c> flags, for various sound and +video output methods, various video codecs and so on. </p> <p> - One of vplayer's optional features is support for the 'fakemedia' codec, - which is unfortunately only available as a dodgy x86 binary. We <e>could</e> - handle this by doing something like: +One of vplayer's optional features is support for the 'fakemedia' codec, +which is unfortunately only available as a dodgy x86 binary. We <e>could</e> +handle this by doing something like: </p> <codesample lang="ebuild"> -RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )" +RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )" </codesample> <p> - Except this is pretty nasty <d/> what happens when an AMD64 binary is made - as well? Also, users on other archs will see fakemedia listed in - <c>emerge -pv</c> output, even though it is not actually available. +Except this is pretty nasty <d/> what happens when an AMD64 binary is made +as well? Also, users on other archs will see fakemedia listed in +<c>emerge -pv</c> output, even though it is not actually available. </p> <p> - Similarly, say vplayer supports output via the ALSA codec as one option. - However, ALSA isn't (or wasn't when this example was written) available on - SPARC or Alpha. So we could do: +Similarly, say vplayer supports output via the ALSA codec as one option. +However, ALSA isn't (or wasn't when this example was written) available on +SPARC or Alpha. So we could do: </p> <codesample lang="ebuild"> @@ -83,67 +161,108 @@ DEPEND="!sparc? ( !alpha? ( alsa? ( media-libs/alsa-lib ) ) )" </codesample> <p> - Again, it's messy, and ALSA still shows up in the <c>emerge -p</c> output. - Also, once ALSA starts working on SPARC, every ebuild that does this would - have to be manually edited. +Again, it's messy, and ALSA still shows up in the <c>emerge -p</c> output. +Also, once ALSA starts working on SPARC, every ebuild that does this would +have to be manually edited. </p> <p> - The solution is <c>use.mask</c>, which is documented in - <uri link="::profiles/use.mask/"/>. Each profile can have a <c>use.mask</c> - file which can be used to forcibly disable certain USE flags on a given - arch (or subarch, or subprofile). So, if the <c>fakemedia</c> USE flag was - use.masked on every non-x86 profile, the following would be totally legal - and wouldn't break anything: +The solution is <c>use.mask</c>, which is documented in +<uri link="::profiles/use.mask/"/>. Each profile can have a <c>use.mask</c> +file which can be used to forcibly disable certain USE flags on a given +arch (or subarch, or subprofile). So, if the <c>fakemedia</c> USE flag was +use.masked on every non-x86 profile, the following would be totally legal +and wouldn't break anything: </p> <codesample lang="ebuild"> -RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )" +RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )" </codesample> <p> - Users of non-x86 would see the following when doing - <c>emerge -pv vplayer</c>: +Users of non-x86 would see the following when doing +<c>emerge -pv vplayer</c>: </p> <pre> - [ebuild R ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz +[ebuild R ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz </pre> <p> - To get a flag added to <c>use.mask</c>, ask the relevant arch team. +To get a flag added to <c>use.mask</c>, ask the relevant arch team. </p> </body> </section> <section> +<title>IUSE defaults</title> +<body> + +<p> +Add <c>+</c> or <c>-</c> before the name of the use flag in <c>IUSE</c> to turn +it on or off by default. +</p> + +<p> +IUSE defaults should be used sparingly. Reasons to exclude/default-disable a +feature may include e.g. large build time for a dependency, or a +configuration that the Gentoo maintainer is unable to test at runtime. +</p> + +<p> +The IUSE defaults for a package should not leave a package in a non-functional +state or lacking important, common functionality. Consulting upstream +documentation may be useful for assessing this. +</p> + +<important> +Adding <c>-</c> before a flag in <c>IUSE</c> is pretty much useless, as it will +neither override the user configuration (<c>make.conf</c>) nor the profile +default (<c>make.defaults</c> and <c>package.use</c>). +See <uri link="::eclass-reference/make.conf/">make.conf(5)</uri> for details +on USE-ordering in Portage. +</important> + +<codesample lang="ebuild"> +# Copyright 1999-2021 Gentoo Authors +# Distributed under the terms of the GNU General Public License v2 + +EAPI=7 + +IUSE="+bar foo" +</codesample> + +</body> +</section> + +<section> <title>Local and Global USE Flags</title> <body> <p> - USE flags are categorised as either local or global. A global USE flag must - satisfy several criteria: +USE flags are categorised as either local or global. A global USE flag must +satisfy several criteria: </p> <ul> <li>It is used by many different packages, at least 5 seems to be agreed upon.</li> - <li>It has a general non-specific purpose.</li> + <li>It has a general non-specific purpose.</li> </ul> <p> - The second point is important. If the effect of the USE flag upon - <c>pkg-one</c> is substantially different from the effect it has upon - <c>pkg-two</c>, then the flag is not a suitable candidate for being made a - global flag. In particular, note that if <c>client</c> and <c>server</c> - USE flags are ever introduced, they can not be global USE flags for this - reason. +The second point is important. If the effect of the USE flag upon +<c>pkg-one</c> is substantially different from the effect it has upon +<c>pkg-two</c>, then the flag is not a suitable candidate for being made a +global flag. In particular, note that if <c>client</c> and <c>server</c> +USE flags are ever introduced, they can not be global USE flags for this +reason. </p> <p> - Before introducing a new global USE flag, it must be discussed on the - gentoo-dev mailing list. +Before introducing a new global USE flag, it must be discussed on the +gentoo-dev mailing list. </p> </body> @@ -153,24 +272,23 @@ RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )" <title>USE Flag Descriptions</title> <body> <p> - All USE flags must be described in either <c>use.desc</c> in the - <c>profiles/</c> directory or <c>metadata.xml</c> in the package's - directory. See <c>man portage</c> or the comments in these files for an - explanation of the format. Remember to keep these files sorted. The file - <c>use.local.desc</c> is automatically generated from entries in the - package's <c>metadata.xml</c> and may be used by tools that parse the tree. - Since <c>use.local.desc</c> is automatically generated it must never be - manually editted in the tree. - See - <uri link="https://wiki.gentoo.org/wiki/GLEP:56">GLEP 56</uri> - for more info. -</p> -<p> - The exceptions to this are <c>USE_EXPAND</c> flags, which must be - documented in the <c>profiles/desc/</c> directory. One file per - <c>USE_EXPAND</c> variable is required, which must contain descriptions of - the possible values this variable can take. See the comments in these files - for the format, and remember to keep them sorted. +All USE flags must be described in either <c>use.desc</c> in the +<c>profiles/</c> directory or <c>metadata.xml</c> in the package's +directory. See <c>man portage</c> or the comments in these files for an +explanation of the format. Remember to keep these files sorted. The file +<c>use.local.desc</c> is automatically generated from entries in the +package's <c>metadata.xml</c> and may be used by tools that parse the tree. +Since <c>use.local.desc</c> is automatically generated it must never be +manually editted in the tree. +See <uri link="https://www.gentoo.org/glep/glep-0056.html">GLEP 56</uri> +for more info. +</p> +<p> +The exceptions to this are <c>USE_EXPAND</c> flags, which must be +documented in the <c>profiles/desc/</c> directory. One file per +<c>USE_EXPAND</c> variable is required, which must contain descriptions of +the possible values this variable can take. See the comments in these files +for the format, and remember to keep them sorted. </p> </body> </section> @@ -179,59 +297,55 @@ RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )" <title>Conflicting USE Flags</title> <body> <p> - Occasionally, ebuilds will have conflicting USE flags for functionality. - Checking for them and returning an error is <e>not</e> a viable solution. - Instead, you must pick one of the USE flags in conflict to favour and should - alert the user that a particular flag is being used instead. +Occasionally, ebuilds will have conflicting USE flags for functionality. +Checking for them and returning an error is <e>not</e> a viable solution. +Instead, you must pick one of the USE flags in conflict to favour and should +alert the user that a particular flag is being used instead. </p> <p> - One example comes from the <c>mail-mta/msmtp</c> ebuilds. The package can - use either SSL with GnuTLS, SSL with OpenSSL, or no SSL at all. Because - GnuTLS is more featureful than OpenSSL, it is favoured: +One example comes from the <c>mail-mta/msmtp</c> ebuilds. The package can +use either SSL with GnuTLS, SSL with OpenSSL, or no SSL at all. Because +GnuTLS is more featureful than OpenSSL, it is favoured: </p> <codesample lang="ebuild"> -src_compile() { - local myconf - - if use ssl && use gnutls ; then - myconf="${myconf} --enable-ssl --with-ssl=gnutls" - elif use ssl && ! use gnutls ; then - myconf="${myconf} --enable-ssl --with-ssl=openssl" - else - myconf="${myconf} --disable-ssl" - fi - - econf \ - # Other stuff - ${myconf} - - emake || die "make failed" +src_configure() { + local myconf + + if use ssl; then + myconf+=" --enable-ssl --with-ssl=$(usex gnutls gnutls openssl)" + else + myconf+=" --disable-ssl" + fi + + econf \ + # Other stuff + ${myconf} } </codesample> <p> - In some exceptional cases, above policy would break reverse USE - dependencies. To avoid this, the ebuild can specify allowed USE flag - combinations with <c>REQUIRED_USE</c> (available in EAPI 4). See section - <uri link="::ebuild-writing/eapi/#eapi=4" /> for a description - of its syntax. +In some exceptional cases, above policy would break reverse USE dependencies. +To avoid this, the ebuild can specify allowed USE flag combinations with +<c>REQUIRED_USE</c>. See section +<uri link="::ebuild-writing/variables/#REQUIRED_USE"/> for a description +of its syntax. </p> <p> - For example, if a package <c>dev-libs/foo</c> can be built with either - <c>USE="a"</c> or <c>USE="b"</c> but not with both, then preferring one of - the flags would break packages that depend on either <c>dev-libs/foo[a]</c> - or <c>dev-libs/foo[b]</c>. Therefore, the ebuild should specify - <c>REQUIRED_USE="a? ( !b )"</c> in this case. +For example, if a package <c>dev-libs/foo</c> can be built with either +<c>USE="a"</c> or <c>USE="b"</c> but not with both, then preferring one of +the flags would break packages that depend on either <c>dev-libs/foo[a]</c> +or <c>dev-libs/foo[b]</c>. Therefore, the ebuild should specify +<c>REQUIRED_USE="a? ( !b )"</c> in this case. </p> <note> - In order to avoid forcing users to micro-manage flags too much, - <c>REQUIRED_USE</c> should be used sparingly. Follow the normal policy - whenever it is possible to do a build that will presumably suit the user's - needs. +In order to avoid forcing users to micro-manage flags too much, +<c>REQUIRED_USE</c> should be used sparingly. Follow the normal policy +whenever it is possible to do a build that will presumably suit the user's +needs. </note> </body> </section> @@ -241,33 +355,32 @@ src_compile() { <body> <p> - The <c>VIDEO_CARDS</c>, <c>INPUT_DEVICES</c> and <c>LINGUAS</c> variables - are automatically expanded into USE flags. These are known as - <c>USE_EXPAND</c> variables. If the user has <c>LINGUAS="en fr"</c> in - <c>make.conf</c>, for example, then <c>USE="linguas_en linguas_fr"</c> will - automatically be set by Portage. +The <c>VIDEO_CARDS</c>, <c>INPUT_DEVICES</c> and <c>L10N</c> variables +are automatically expanded into USE flags. These are known as +<c>USE_EXPAND</c> variables. If the user has <c>L10N="en fr"</c> in +<c><uri link="::eclass-reference/make.conf/"/></c>, for example, then +<c>USE="l10n_en l10n_fr"</c> will automatically be set by Portage. </p> <p> - The <c>USE_EXPAND</c> list is set in <c>profiles/base/make.defaults</c> as of - Portage 2.0.51.20. This must not be modified without discussion on the - gentoo-dev list, and it must not be modified in any subprofile. +The <c>USE_EXPAND</c> list is set in <c>profiles/base/make.defaults</c> as of +Portage 2.0.51.20. This must not be modified without discussion on the +gentoo-dev list, and it must not be modified in any subprofile. </p> <p> - The current architecture (e.g. <c>x86</c>, <c>sparc</c>, <c>ppc-macos</c>) - will automatically be set as a USE flag as well. See - <c>profiles/arch.list</c> for a full list of valid architecture keywords, - and - <uri link="https://wiki.gentoo.org/wiki/GLEP:22">GLEP 22</uri> - for an explanation of the format. +The current architecture (e.g. <c>x86</c>, <c>sparc</c>, <c>ppc-macos</c>) +will automatically be set as a USE flag as well. See +<c>profiles/arch.list</c> for a full list of valid architecture keywords, +and <uri link="https://www.gentoo.org/glep/glep-0022.html">GLEP 22</uri> +for an explanation of the format. </p> <warning> - It is a common misconception that the architecture variable is somehow - related to <c>ACCEPT_KEYWORDS</c>. It isn't. Accepting <c>x86</c> keywords - on <c>sparc</c>, for example, won't set <c>USE="x86"</c>. Similarly, there - are no <c>~arch</c> USE flags, so don't try <c>if use ~x86</c>. +It is a common misconception that the architecture variable is somehow +related to <c>ACCEPT_KEYWORDS</c>. It isn't. Accepting <c>x86</c> keywords +on <c>sparc</c>, for example, won't set <c>USE="x86"</c>. Similarly, there +are no <c>~arch</c> USE flags, so don't try <c>if use ~x86</c>. </warning> </body> diff --git a/general-concepts/user-environment/text.xml b/general-concepts/user-environment/text.xml index b7a0926..b472ea5 100644 --- a/general-concepts/user-environment/text.xml +++ b/general-concepts/user-environment/text.xml @@ -1,16 +1,18 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/user-environment/"> <chapter> <title>User Environment</title> - <body> + <p> -User environment variables and <c>make.conf</c> settings get passed on to ebuilds. -This can be useful <d/> it's how <c>CFLAGS</c> and friends work, for example <d/> but -it can also result in nasty build-breaking variables like <c>LANG</c> and -<c>LC_ALL</c> getting through. Currently no sanitisation is performed upon the -environment. +User environment variables and +<c><uri link="::eclass-reference/make.conf/"/></c> settings get passed on +to ebuilds. This can be useful <d/> it's how <c>CFLAGS</c> and friends work, +for example <d/> but it can also result in nasty build-breaking variables like +<c>LANG</c> and <c>LC_ALL</c> getting through. Currently no sanitisation is +performed upon the environment. </p> + </body> <section> @@ -30,10 +32,10 @@ The simplest way to unset all locale-related variables is: <codesample lang="ebuild"> pkg_setup() { - # Unset all locale related variables, they can make the - # build fail. + # Unset all locale related variables, they can make the + # build fail. - eval unset ${!LC_*} LANG + eval unset ${!LC_*} LANG } </codesample> </body> diff --git a/general-concepts/virtuals/text.xml b/general-concepts/virtuals/text.xml index 96d9ba3..62c739d 100644 --- a/general-concepts/virtuals/text.xml +++ b/general-concepts/virtuals/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/virtuals/"> <chapter> <title>Virtuals</title> @@ -6,7 +6,7 @@ <body> <p> Virtuals are merely packages that are in the category of <c>virtual</c>. They -use their dependency string to specify the providers for the virtual and should +use their dependency string to specify the providers for the virtual and do not install any files. Since they are regular ebuilds, there can be several versions of a virtual (which can be helpful when a package may be provided by another in some versions, and not others <d/> see the perl virtuals for an @@ -21,26 +21,138 @@ Before adding a new virtual, it should be discussed on <c>gentoo-dev</c>. <p> An example of a virtual: +</p> <codesample lang="ebuild"> -EAPI=4 +EAPI=8 DESCRIPTION="Virtual for C++ tr1 <type_traits>" SLOT="0" -KEYWORDS="alpha amd64 arm hppa ia64 ~mips ppc ppc64 ~s390 sparc x86 ~x86-fbsd" +KEYWORDS="~alpha amd64 arm hppa ~ia64 ~mips ppc ppc64 ~s390 sparc x86 ~x64-macos" -RDEPEND="|| ( >=sys-devel/gcc-4.1 dev-libs/boost )" +RDEPEND="|| ( >=sys-devel/gcc-4.1 dev-libs/boost )" </codesample> -Looks familar...right? It should since its going to look just like a regular +<p> +Looks familar...right? It should since it's going to look just like a regular ebuild. </p> <note> The so-called <e>old-style</e> or <c>PROVIDE</c> type virtuals have been banned -from the Portage tree. +from the Gentoo repository. +</note> +</body> + +<section> +<title>KEYWORDS in virtual packages</title> + +<body> +<p> +Since virtual packages do not install any files, they do not follow the regular +arch testing procedure. Instead, the developer can immediately set +the <c>KEYWORDS</c> of a virtual to the union of <c>KEYWORDS</c> of its +providers. In particular, if a new virtual is created for a stable package, +the virtual is committed straight to stable. +</p> + +<p> +For example, if you have two packages: <c>dev-libs/liblinux</c> with +<c>KEYWORDS="amd64 ~x86"</c> and <c>dev-libs/libbsd</c> with +<c>KEYWORDS="~amd64-fbsd ~x86-fbsd"</c>, the resulting virtual will +have: +</p> + +<codesample lang="ebuild"> +KEYWORDS="amd64 ~x86 ~amd64-fbsd ~x86-fbsd" + +RDEPEND="|| ( dev-libs/liblinux dev-libs/libbsd )" +</codesample> +</body> + +</section> + +<section> +<title>Virtuals and subslots</title> + +<body> +<warning> +This section is only applicable if virtual providers include versions that +are ABI-compatible with one another (and use matching SONAMEs) and/or +the incompatible providers are being obsoleted. +</warning> + +<p> +Like regular packages, virtuals can define subslots that can be used +to trigger rebuilds of their reverse dependencies. For this to work, a new +version of the virtual is created for each subslot of the providers, +where each version contains dependencies on a specific subslot. +</p> + +<p> +For example, a virtual for different packages providing ABI-compatible +<c>libfoo.so.1</c> libraries could look like the following: +</p> + +<codesample lang="ebuild"> +EAPI=8 + +DESCRIPTION="Virtual for libfoo.so.1" +SLOT="0/1" + +RDEPEND=" + || ( + dev-libs/libfoo:0/1 + dev-libs/libfoo-alternate:0/1 + dev-libs/bigpack:0/libfoo-1+libbar-0 + dev-libs/bigpack:0/libfoo-1+libbar-1 + ) +" +</codesample> + +<p> +Virtuals can also be used when one of the providers is being obsoleted in favor +of another that breaks ABI compatibility while remaining API-compatible. In this +case, multiple versions of the virtual are created, each specifying a single +provider and a unique subslot. +</p> + +<p> +For example, if <c>dev-libs/libfoo</c> (<c>libfoo.so.0</c>) is being replaced +by <c>dev-libs/newfoo</c> (<c>libfoo.so.1</c>), <c>virtual/libfoo-0.ebuild</c> +would contain: +</p> + +<codesample lang="ebuild"> +EAPI=8 + +DESCRIPTION="Virtual for libfoo.so.0" +SLOT="0/0" + +RDEPEND="dev-libs/libfoo:0/0" +</codesample> + +<p> +while <c>virtual/libfoo-1.ebuild</c> would contain: +</p> + +<codesample lang="ebuild"> +EAPI=8 + +DESCRIPTION="Virtual for libfoo.so.1" +SLOT="0/1" + +RDEPEND="dev-libs/newfoo:0/1" +</codesample> + +<note> +In this case, the package manager will naturally want to upgrade +to <c>dev-libs/newfoo</c> whenever possible. Therefore, this solution +is not viable if a clean choice between the two providers is desired. </note> + </body> +</section> </chapter> </guide> diff --git a/hosted-projects/text.xml b/hosted-projects/text.xml index 55a6b8a..d7e5ec9 100644 --- a/hosted-projects/text.xml +++ b/hosted-projects/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="hosted-projects/"> <chapter> <title>Hosted Projects</title> @@ -8,6 +8,7 @@ The following guidelines have been proposed for hosted projects in an attempt to prevent a repeat of the <c>genkernel</c> disaster. </p> +</body> <section> <title>Documentation Requirement</title> @@ -112,8 +113,9 @@ In practice, this means the following: <p> All hosted projects should use an appropriate open / free / libre license. -Typically this will be the GPL v2 for software, and the Creative Commons license -for documentation. However, reasonable exceptions can be made <d/> sometimes it +Typically this will be the GPL v2 for software, and some version of the +Creative Commons Attribution-ShareAlike License (CC-BY-SA-*) for documentation. +However, reasonable exceptions can be made <d/> sometimes it makes more sense to use the LGPL or a *BSD license, and for application-specific projects going with the application's license may make more sense (the <c>gentoo-syntax</c> package for <c>vim</c> uses the <c>vim</c> license, for example). @@ -149,18 +151,16 @@ Good places to look for further hints include: <ul> <li> - <uri link="http://developer.gnome.org/projects/gap">GNOME Accessibility + <uri link="https://developer.gnome.org/accessibility-devel-guide/stable/gad.html.en">GNOME Accessibility Project</uri> </li> <li> - <uri link="http://www.w3.org/WAI/Resources/#gl">W3C Web Accessibility + <uri link="https://www.w3.org/WAI/Resources/#guides">W3C Web Accessibility Initiative Guidelines</uri> </li> </ul> </body> </section> - -</body> </chapter> </guide> diff --git a/icons/icon_mini-creativecommons.png b/icons/icon_mini-creativecommons.png Binary files differdeleted file mode 100644 index f50c656..0000000 --- a/icons/icon_mini-creativecommons.png +++ /dev/null diff --git a/icons/icon_mini-css.png b/icons/icon_mini-css.png Binary files differdeleted file mode 100644 index 44d3ead..0000000 --- a/icons/icon_mini-css.png +++ /dev/null diff --git a/icons/icon_mini-gentoo.png b/icons/icon_mini-gentoo.png Binary files differdeleted file mode 100644 index 4eb1426..0000000 --- a/icons/icon_mini-gentoo.png +++ /dev/null diff --git a/icons/icon_mini-xhtml.png b/icons/icon_mini-xhtml.png Binary files differdeleted file mode 100644 index 29fd40e..0000000 --- a/icons/icon_mini-xhtml.png +++ /dev/null diff --git a/icons/icon_mini-xml.png b/icons/icon_mini-xml.png Binary files differdeleted file mode 100644 index 07c1ec5..0000000 --- a/icons/icon_mini-xml.png +++ /dev/null diff --git a/keywording/text.xml b/keywording/text.xml index e22a76a..4d87934 100644 --- a/keywording/text.xml +++ b/keywording/text.xml @@ -1,25 +1,25 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="keywording/"> <chapter> -<title>Keywording</title> +<title>Keywording and Stabilization</title> <body> <note> -<e>Terminology</e>: The term 'package' refers to an entire directory, for example -<c>app-editors/vim</c> <d /> it does <e>not</e> refer to a specific version. The terms -'ebuild' or 'package version' are used when this meaning is intended. This -distinction is important. +<e>Terminology</e>: The term 'package' refers to an entire directory, for +example <c>app-editors/vim</c> <d /> it does <e>not</e> refer to a specific +version. The terms 'ebuild' or 'package version' are used when this meaning is +intended. This distinction is important. </note> <p> -Every ebuild must specify a <c>KEYWORDS</c> variable. This variable is used to +Most ebuilds specify a <c>KEYWORDS</c> variable. This variable is used to indicate the suitability and stability of both the package and the ebuild on -each given arch (<c>sparc</c>, <c>ppc</c>, <c>x86-obsd</c>, ...). +each given arch (<c>sparc</c>, <c>ppc</c>, <c>x64-macos</c>, ...). </p> <note> The term 'arch' is used in this sense for historical reasons. As a result -of <uri link="https://wiki.gentoo.org/wiki/GLEP:22">GLEP 22</uri> +of <uri link="https://www.gentoo.org/glep/glep-0022.html">GLEP 22</uri> and the various non-Linux ports, this is no longer a particularly accurate term. </note> @@ -29,7 +29,7 @@ A sample <c>KEYWORDS</c> entry might look like: </p> <codesample lang="ebuild"> -KEYWORDS="x86 sparc ~mips ~ppc ~ppc-macos -ia64" +KEYWORDS="-ia64 ~mips ~ppc sparc x86 ~ppc-macos" </codesample> <p> @@ -38,89 +38,89 @@ The different levels of keyword are: <dl> <dt> - <c>arch</c> (<c>x86</c>, <c>ppc-macos</c>) + <c>arch</c> (<c>x86</c>, <c>ppc-macos</c>) ("stable") </dt> <dd> - <p> - Both the package version <e>and</e> the ebuild are widely tested, known to work - and not have any serious issues on the indicated platform. - </p> + Both the package version <e>and</e> the ebuild are widely tested, known to + work and not have any serious issues on the indicated platform. </dd> <dt> - <c>~arch</c> (<c>~x86</c>, <c>~ppc-macos</c>) + <c>~arch</c> (<c>~x86</c>, <c>~ppc-macos</c>) ("testing") </dt> <dd> - <p> The package version and the ebuild are believed to work and do not have any known serious bugs, but more testing is required before the package version is considered suitable for <c>arch</c>. - </p> </dd> <dt> - No keyword + No keyword ("unkeyworded") </dt> <dd> - <p> If a package has no keyword for a given arch, it means it is not known whether the package will work, or that insufficient testing has occurred for <c>~arch</c>. - </p> </dd> <dt> <c>-arch</c> (<c>-x86</c>, <c>-ppc-macos</c>) </dt> <dd> - <p> The package version will not work on the arch. This could be caused by badly written code (for example, non-64-bit or endian clean code), relying upon particular hardware (for example, a BIOS querying tool would not work on non-BIOS architectures) or binary only packages. - </p> </dd> </dl> <p> -The <c>-*</c> keyword is special. It is used to indicate package versions which are -not worth trying to test on unlisted archs. For example, a binary-only package -which is only supported upstream on <c>x86</c> and <c>ppc</c> might use: +The <c>-*</c> keyword is special. It is used to indicate package versions which +are not worth trying to test on unlisted arches. For example, a binary-only +package which is only supported upstream on <c>ppc</c> and <c>x86</c> might +use: </p> <codesample lang="ebuild"> -KEYWORDS="-* x86 ppc" +KEYWORDS="-* ppc x86" </codesample> <p> -This is different in implication from <c>"x86 ppc"</c> <d /> the former implies that -it will not work on other archs, whereas the latter implies that it has not been -tested. +This is different in implication from <c>"ppc x86"</c> <d/> the former implies +that it will not work on other arches, whereas the latter implies that it has +not been tested. </p> <p> Do <b>not</b> use the <c>*</c> or <c>~*</c> special keywords in ebuilds. </p> +<note> +Usually, "live" ebuilds +(see <uri link="::ebuild-writing/functions/src_unpack/vcs-sources/"/>) +do not specify a <c>KEYWORDS</c> variable. +</note> +</body> + <section> <title>Equal Visibility Requirement</title> <body> <p> -An ebuild <b>must not</b> depend upon any package that is of a lower keyword level -than itself. For example, if <c>foo-1.2</c> depends upon <c>bar-1.2</c>, and -<c>bar-1.2</c> is <c>~x86</c>, then <c>foo-1.2</c> must <b>not</b> be marked stable on -<c>x86</c> unless <c>bar-1.2</c> is also stabilised. +An ebuild <b>must not</b> depend upon any package that is of a lower keyword +level than itself. For example, if <c>foo-1.2</c> depends upon <c>bar-1.2</c>, +and <c>bar-1.2</c> is <c>~x86</c>, then <c>foo-1.2</c> must <b>not</b> be marked +stable on <c>x86</c> unless <c>bar-1.2</c> is also stabilised. </p> <p> -You may assume that if a user accepts <c>~arch</c> for a given arch then they also -accept <c>arch</c>. +You may assume that if a user accepts <c>~arch</c> for a given arch then they +also accept <c>arch</c>. </p> <p> -For optional dependencies, all <e>possible</e> dependencies must satisfy the above. -Note that certain <c>USE</c> flags can be forcibly disabled on a per-profile basis -<d /> talk to the arch teams if you require this. For either-or dependencies, <e>at -least one</e> of the options must be of equal or better visibility than the -package in question. +For optional dependencies, all <e>possible</e> dependencies must satisfy the +above. Note that certain <c>USE</c> flags can be forcibly disabled on a +per-profile basis <d /> talk to the arch teams if you require this. For +either-or dependencies, <e>at least one</e> of the options must be of equal or +better visibility than the package in question. </p> </body> @@ -139,11 +139,17 @@ packages. </p> <p> +It is good practice to file a bug for ebuilds listed in <c>package.mask</c> to +allow feedback to be gathered in one location and to reduce the chance of +forgetting about it. Mention the bug number in the mask message. +</p> + +<p> The only time it is acceptable for a user to see the <c>Possibly a DEPEND -problem</c> error message is if they have manually changed visibility levels for a -package (for example, through <c>/etc/portage/</c>) and have missed a dependency. -<b>You should never commit a change which could cause this error to appear on a -user system</b>. +problem</c> error message is if they have manually changed visibility levels for +a package (for example, through <c>/etc/portage/</c>) and have missed a +dependency. <b>You should never commit a change which could cause this error to +appear on a user system</b>. </p> </body> @@ -154,40 +160,42 @@ user system</b>. <body> <important> -New packages should be marked as <c>~arch</c> only upon -architectures for which the committing developer has tested. +New packages should be marked as <c>~arch</c> ("testing") only upon +architectures for which the committing developer has tested. If proxying +commits for a non-developer, please ensure they have some relationship +with the relevant arch teams, or <d/> better yet <d/> ask them to file +a keywording bug instead for non-<c>amd64</c>/<c>x86</c>. </important> <p> Do <b>not</b> assume that your package works on all architectures. Do <b>not</b> -assume that user submitted ebuilds will have correct <c>KEYWORDS</c> <d /> chances are -they just copied from somewhere else. Do <b>not</b> assume that upstream's -'supported architectures' list is correct. Do <b>not</b> assume that because your -code is written in Perl / Python / Java / whatever that it will run on other -archs (there is at least one case of a <c>vim</c> script which only worked on -<c>x86</c>). +assume that user submitted ebuilds will have correct <c>KEYWORDS</c> <d /> +chances are they just copied from somewhere else. Do <b>not</b> assume that +upstream's 'supported architectures' list is correct. Do <b>not</b> assume that +because your code is written in Perl / Python / Java / whatever that it will run +on other arches (there is at least one case of a <c>vim</c> script which only +worked on <c>x86</c>). </p> <p> -Note that most (non-x86) archs expect you to be on the arch team and bugzilla -alias if you are committing packages with keywords for that arch, and may have -additional requirements of which you should be aware (on <c>mips</c>, for example, -there are multiple ABIs and byte orders to consider <d /> a package working on your -<c>o32</c> box may not work on <c>o64</c> or <c>n32</c>). Contact the individual arch -teams for details. +Note that most (non-<c>amd64</c>/<c>x86</c>) arches expect you to be on the +arch team and bugzilla alias if you are committing packages with keywords for +that arch, and may have additional requirements of which you should be aware +(on <c>mips</c>, for example, there are multiple ABIs and byte orders to +consider <d/> a package working on your <c>o32</c> box may not work on +<c>o64</c> or <c>n32</c>). Contact the individual arch teams for details. </p> <p> - It's important to note that alternative arches (like alpha, ia64, s390, - sh, sparc, hppa, ppc*) are mainly undermanned arches, some of them are - slow, they have more basic problems and have a small userbase. Just file - bugs for these architectures when a package is going to be a dependency of a - package already keyworded. +It's important to note that alternative arches (like <c>alpha</c>, <c>ia64</c>, +<c>s390</c>, <c>sparc</c>, <c>hppa</c>, <c>ppc*</c>) are mainly understaffed +arches, some of them are slow, they have more basic problems and have a small +userbase. Just file bugs for these architectures when a package is going to be +a dependency of a package already keyworded. </p> - <p> -Do <b>not</b> commit straight to <c>arch</c>. +Do <b>not</b> commit straight to <c>arch</c> ("stable"). </p> </body> @@ -198,22 +206,45 @@ Do <b>not</b> commit straight to <c>arch</c>. <body> <p> -When upgrading, drop all existing keywords from <c>arch</c> to <c>~arch</c>, and leave -any existing <c>~arch</c> keywords intact. This must be done even if you <e>think</e> +When upgrading, drop all existing keywords from <c>arch</c> to <c>~arch</c> +("testing"), and leave any existing <c>~arch</c> keywords intact. It's easiest +and safest to use <c>ekeyword ~all my-new-version.ebuild</c> from the <c> +app-portage/gentoolkit</c> package. This must be done even if you <e>think</e> you're just making a trivial fix <d /> there have been several examples of the stable tree getting broken this way. </p> <p> -Sometimes you may need to remove a keyword because of new unresolved -dependencies. If you do this, you <b>must</b> file a bug notifying the relevant -arch teams. +This also applies to revision bumps, not just to upstream version changes. </p> <p> -This also applies to revision bumps, not just to upstream version changes. +If a new version introduces new dependencies which are not available on some +architectures, then you should file a bug or ask on IRC before you upgrade the +ebuild. If you really need to get the ebuild added in a hurry, for example, +for a security fix, then you should drop any <c>KEYWORDS</c> which are causing +problems and CC the relevant architectures on the bug <d/> you <b>must</b> file +a <uri link="https://projects.gentoo.org/qa/policy-guide/keywords.html#pg0401"> +new bug</uri> to the architecture in question regarding this if no bug is +already available. +</p> + +<p> +Note that it is preferred to drop keywords on the package and request +rekeywording of it together with its new dependencies within the same bug to +allow the new code path(s) in your package to be tested. This won't happen if +the new dependency is requested for keywording by itself and +<c>package.use.mask</c> is used to mask the relevant new USE flag: only the +new package dependency will be tested by arch testers. Also, the mask has to be +manually removed during the testing process, which is cumbersome. </p> +<important> +When committing, make sure that you reference any bugs in the commit message. +See <uri link="::ebuild-maintenance/git/#Git Commit Message Format"/> for how +to do this. +</important> + </body> </section> @@ -222,50 +253,247 @@ This also applies to revision bumps, not just to upstream version changes. <body> <p> -Moving a package from <c>~arch</c> to <c>arch</c> is done only by the relevant arch teams. -If you have access to non-x86 hardware but are not on the arch teams, you may wish -to make individual arrangements <d /> the arch teams are happy for help, so long as -they know what is going on. Please note that <c>x86</c> is now no longer an exception -and stabilisation must be done through the <c>x86</c> arch team unless you have -individual arrangements <d /> see -<uri link="https://wiki.gentoo.org/wiki/GLEP:40">GLEP 40</uri> -for further details. +If a package has stable keywords, maintainers should regularly (subject to the +rules below) file stabilization bugs for their packages, ideally approximately +every 30 days after a new version is added. If a bug report for stabilization +is filed by somebody else, the maintainer should respond with an +acknowledgement ("ACK") if the ebuild is ready, and a negative +acknowledgement ("NAK") if not. +</p> + +<p> +Previous stable keywords should not be dropped without good cause and it is +courteous to ping members of the relevant arch team first. Maintainers must not +drop stable keywords simply because they don't have access to a platform: this +is what Gentoo's arch teams are here for. +</p> + +<p> +By convention, these bugs are assigned to package maintainers, but the only +action expected from maintainers is to acknowledge or reject the +stabilization rather than carry out additional testing on each required +architecture themselves. +</p> + +<p> +Stabilization, i.e., moving an ebuild from <c>~arch</c> ("testing") to +<c>arch</c> ("stable"), is done by the relevant architecture teams. If you have +access to exotic hardware but are not on the arch teams, you may wish to make +individual arrangements <d/> the arch teams are happy for help, so long as they +know what is going on. +</p> + +<p> +In order to request stabilization of an ebuild, file a bug to the package's +maintainer (which may be yourself) in the Stabilization component, and list +all secondary maintainers in the bug's CC. When the maintainers consider the +ebuild to be ready for stabilization, they will add the relevant architecture +teams to the CC list. They can fill the package +list field, add the <c>CC-ARCHES</c> keyword, and let +<uri link="https://dev.gentoo.org/~mgorny/doc/nattka/">NATTkA</uri> +automatically add arch teams to CC (preferred), or do this manually. +That way, teams can remove themselves from the list when they are done, giving +a clear indication of which teams still remain to stabilize a package. +</p> + +<p> +It is <e>strongly</e> +<uri link="https://archives.gentoo.org/gentoo-dev/message/cd62f6be924f6a0f76b68a07d33b256a"> +recommended</uri> that <c>NATTkA</c> be used to file keywording or +stabilization bugs to ensure that arches are not accidentally forgot about; +the automation removes an often error-prone step in the arch-testing process. +Ask in #gentoo-dev or on the gentoo-dev mailing list if you need help. +</p> + +<p> +<c>NATTkA</c> will set the <c>sanity-check</c> field on Bugzilla to either +<c>-</c> or <c>+</c> depending on whether the package list results in a +consistent dependency graph. You may need to add more packages or adjust the +arches listed for each package based on the output the bot posts as a comment +on the bug. Please note that arch teams may not process or notice bugs with a +blank or <c>-</c> sanity-check, so please fix this if it occurs <d/> or ask for +help to do so. +</p> + +<note> +In addition, if you are changing the package list of a bug after it has been +processed, <d/> i.e. after NATTkA has CCed arches <d/> you should un-CC all +arches so that NATTkA CCs the new correct set of arches. +</note> + +<note> +Note that sometimes NATTkA may do <e>nothing</e> if it has concluded the package +list is complete. You may wish to run <c>nattka sanity-check BUG</c> where +<c>BUG</c> is the bug number you're having an issue with in order to debug the +issue to receive verbose output. +</note> + +<p> +You may wish to read NATTkA's +<uri link="https://github.com/mgorny/nattka#filing-keywordingstabilization-bugs"> +documentation</uri> for help on package list syntax or other information about +the tool. The documentation details syntax which can be used, such as <c>*</c> +to represent "all previously stable arches", or <c>^</c> to copy the arches +from the line(s) above. </p> <p> -For a package to move to stable, the following guidelines must be met: +For an ebuild to move to stable, the following guidelines must be met +(see <uri link="https://www.gentoo.org/glep/glep-0040.html">GLEP 40</uri> +for further details): </p> <ul> <li> - The package has spent a reasonable amount of time in <c>~arch</c> first. Thirty - days is the usual figure, although this is clearly only a guideline. For - critical packages, a much longer duration is expected. For small packages - which have only minor changes between versions, a shorter period is sometimes - appropriate. + The ebuild has spent a reasonable amount of time in <c>~arch</c> first. + Thirty days is the usual figure, although this is clearly only a guideline. + For critical packages, a much longer duration is expected. For small + packages that have only minor changes between versions, a shorter period is + sometimes appropriate. </li> <li> - The package must not have any non-<c>arch</c> dependencies. + The ebuild must not have any non-<c>arch</c> dependencies. </li> <li> - The package must not have any severe outstanding bugs or issues. + The package version (and the ebuild) must not have any severe outstanding + bugs or issues. </li> <li> - The package must be widely tested. + The package version must be widely tested. </li> <li> - If the package is a library, it should be known not to break any package which - depends upon it. + If the package is a library, it should be known not to break any package + which depends upon it. </li> </ul> <p> For security fixes, the "reasonable amount of time" guideline may be relaxed. -See the <uri link="http://www.gentoo.org/security/en/vulnerability-policy.xml"> -Vulnerability Treatment Policy</uri> +See the <uri link="https://www.gentoo.org/support/security/vulnerability-treatment-policy.html"> +Vulnerability Treatment Policy</uri>. +</p> + +</body> + +<subsection> +<title>Stabilization rules</title> +<body> + +<p> +These are rules for stabilizing packages <e>by yourself</e> on a particular +architecture, <e>not</e> for filing bugs to request arch teams to handle it. +</p> + +<ul> + <li> + <c>amd64</c>, <c>x86</c>: If you are the maintainer of a package and own + the respective <c>amd64</c> or <c>x86</c> hardware, you can do your own + testing (stabilization and keywording) of your packages; as long as it is + not a core system set dependency. Note that it is acceptable to test + <c>x86</c> using a + <uri link="https://wiki.gentoo.org/wiki/Project:AMD64/32-bit_Chroot_Guide"> + specialized environment</uri> on <c>amd64</c>. + </li> + + <li> + <c>arm</c>, <c>arm64</c>: These teams have a strict policy on passing + testsuites. You <b>must</b> run test suites for packages with e.g. + <c>FEATURES=test</c> for Portage. Keywording or stabilizing packages which + fail these tests is avoided but acceptable if the test suite is fragile or + failures are known and reported. It is preferred to have to keyword or + stabilize more packages on these arches if needed for e.g. test dependencies + rather than masking or disabling tests here. + </li> + + <li> + <c>sparc</c>: You must have prior permission from the arch lead. Usually we + expect you to be on the sparc alias for QA reasons, although other + arrangements can be made if you will only be working with a small group of + packages. + </li> +</ul> + +<p> +Exotic architectures (like <c>hppa</c>, <c>ppc*</c>, <c>sparc</c>) +are short on help, so it's best if you avoid opening bugs for stabilization +of new packages for them, unless it is absolutely necessary (e.g., a reverse +dependency for your package). +</p> + +<p> +Some architectures (<c>alpha</c>, <c>ia64</c>, <c>mips</c>, <c>riscv</c>, +<c>s390</c>) do not maintain a stable keyword, so packages are not to be marked +stable for one of these architectures. +</p> + +</body> +</subsection> + +<subsection> +<title>Keeping track of pending stabilizations</title> +<body> + +<p> +Maintainers need some method or system to organize and start pending +stabilizations once they become due. +</p> + +<p> +There are several tools available that can help with this: +</p> + +<ul> + <li> + Use <c>imlate</c> from app-portage/gentoolkit + </li> + <li> + Use packages.gentoo.org's maintainer pages (which have a Stabilization + tab) + </li> + <li> + Use <c>pkgcheck</c>'s <c>StableRequest</c> check, e.g. + <c>grep -ri "larry@" */*/metadata.xml -l | cut -d'/' -f1-2 | xargs pkgcheck scan -k StableRequest</c> + </li> +</ul> + +</body> +</subsection> + +<subsection> +<title>Simultaneous stabilization on all architectures</title> +<body> + +<p> +If you maintain an architecture-independent package (data files, icons, pure +Python, ...), then you may request that your package be stabilized on all arches +at once. To do this <d/> when you are filing the stabilization bug <d/> please +add the keyword <c>ALLARCHES</c> and CC the arches that you would like to +stabilize. +</p> + +<p> +If your package is architecture-independent, you should add the +<c><stabilize-allarches/></c> tag to metadata.xml. This allows consistency +in future stabilizations and saves arch teams considerable work. +</p> + +<p> +The arch teams, when encountering the <c>ALLARCHES</c> keyword, should perform +their usual set of tests on a single convenient architecture. Then, if +everything works, stabilize not only the arch that was used during testing, +but also all of the other arches in CC on the bug. Afterwards, the CC field can +be cleared and the bug closed if appropriate. +</p> + +<p> +Note that first-time <c>ALLARCHES</c> stabilizations are done "as normal" <d/> +i.e. all arch teams test individually as if it was not set. This nuance in the +procedure is part of why developers should not manually set <c>ALLARCHES</c> in +bugs, but instead let <c>NATTkA</c> set it automatically based on metadata.xml. </p> </body> +</subsection> </section> <section> @@ -280,9 +508,9 @@ any given keyword level on any profile. The aim here is: <ul> <li> Never to force a downgrade. (Exception: occasionally you really do want to - force a downgrade, for example if the newly committed <c>foo-1.3</c> turns out - to be badly broken and that making everyone downgrade to <c>foo-1.2</c> is the - better option. This is rare.) + force a downgrade, for example if the newly committed <c>foo-1.3</c> turns + out to be badly broken and that making everyone downgrade to <c>foo-1.2</c> + is the better option. This is rare.) </li> <li> Do not break any existing dependencies. @@ -290,13 +518,11 @@ any given keyword level on any profile. The aim here is: </ul> <p> -If you would like a particular package version moved to stable on certain archs +If you would like a particular package version moved to stable on certain arches so that you can tidy up, file a bug. </p> </body> </section> - -</body> </chapter> </guide> diff --git a/offline.css b/offline.css new file mode 100644 index 0000000..463eebc --- /dev/null +++ b/offline.css @@ -0,0 +1,45 @@ +body { + margin: 40px auto; + max-width: 650px; + line-height: 1.6; + font-size: 18px; + color: #454545; + background-color: #fafafa; + padding: 0 10px; +} + +header, footer { + padding: 0.75em 1em; + margin: 1em 0; + background-color: #e1e1e1; +} + +h1, h2, h3, h4, h5, h6 { + line-height: 1.2; +} + +nav.offline ul, .breadcrumb { + list-style-type: none; + padding: 0; + margin: 0; +} + +nav.offline li, .breadcrumb li { + display: inline; +} + +nav.offline li+li { + margin-left: 1em; +} + +.breadcrumb li+li:before { + content: " / "; +} + +.fa-arrow-left:after { + content: "\25c4"; /* BLACK LEFT-POINTING POINTER */ +} + +.fa-arrow-right:after { + content: "\25ba"; /* BLACK RIGHT-POINTING POINTER */ +} diff --git a/profiles/categories/text.xml b/profiles/categories/text.xml index c04c1c1..70dfe8f 100644 --- a/profiles/categories/text.xml +++ b/profiles/categories/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/categories/"> <chapter> <title>Profiles <c>categories</c> File</title> @@ -6,11 +6,15 @@ <body> <p> The <c>profiles/categories</c> file contains an asciibetically sorted list of all -the valid categories in the portage tree. When adding a new category, remember +the valid categories in the Gentoo repository. When adding a new category, remember to update and commit this file <e>before</e> making any related commits. </p> <p> +Please consult the gentoo-dev mailing list before adding a new category. +</p> + +<p> The <c>categories</c> file is a straight list. For descriptions, see <uri link="::ebuild-writing/misc-files/metadata/#Category Metadata"/>. </p> diff --git a/profiles/info_files/text.xml b/profiles/info_files/text.xml index ae68b30..29258be 100644 --- a/profiles/info_files/text.xml +++ b/profiles/info_files/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/info_files/"> <chapter> <title>Profiles <c>info_</c> Files</title> diff --git a/profiles/make.defaults/text.xml b/profiles/make.defaults/text.xml index 15ea2c6..1be4bde 100644 --- a/profiles/make.defaults/text.xml +++ b/profiles/make.defaults/text.xml @@ -1,15 +1,16 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/make.defaults/"> <chapter> <title>Profiles <c>make.defaults</c> File</title> <body> <p> -The <c>make.defaults</c> file in <c>profiles/</c> provides a minimal set of defaults -for the kinds of values which may be set in <c>make.conf</c> (<c>CFLAGS</c>, <c>USE</c>, -<c>FEATURES</c> etc) along with certain control variables (eg <c>USE_EXPAND</c>). -These values can further be refined by additional <c>make.defaults</c> files in -subprofiles. +The <c>make.defaults</c> file in <c>profiles/</c> provides a minimal set +of defaults for the kinds of values which may be set in +<c><uri link="::eclass-reference/make.conf/"/></c> (<c>CFLAGS</c>, +<c>USE</c>, <c>FEATURES</c> etc.) along with certain control variables +(e.g. <c>USE_EXPAND</c>). These values can further be refined by additional +<c>make.defaults</c> files in subprofiles. </p> <p> diff --git a/profiles/package.mask/text.xml b/profiles/package.mask/text.xml index ef57b28..7f8c84a 100644 --- a/profiles/package.mask/text.xml +++ b/profiles/package.mask/text.xml @@ -1,14 +1,42 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/package.mask/"> <chapter> <title>Profiles <c>package.mask</c> File</title> <body> <p> -The <c>package.mask</c> file can be used to hard mask packages or certain versions -of packages. This is often used when adding certain experimental (either in -ebuild or upstream terms) packages to the tree. The format is described in -<c>man portage</c>. +The <c>package.mask</c> file can be used to hard mask packages or +certain versions of packages that should not be merged by users. +This is often used when adding certain experimental (either in ebuild +or upstream terms) packages to the tree, or to prevent merging of +packages that are broken or break something else. Every entry should +have a comment detailing the specific reason for the mask. The format +of the <c>package.mask</c> file is described in <c>man portage</c>. +</p> + +<p> +Development or unstable (per upstream declaration/categorization) versions of +packages should usually be masked in <c>package.mask</c>. Upstreams may not +deem such releases to be ready for general distribution (or safe to use), or +may not be expecting bug reports from the wider userbase yet. The default +should generally be to mask such versions, but it is acceptable to not mask +in some circumstances <d/> e.g. upstream make very infrequent releases, the +changes are safe (reviewed by the Gentoo maintainer), or perhaps other +distributions are shipping the same new version. As an alternative to a +development version, you may also consider backporting required upstream fixes +to the released version. +</p> + +<p> +Overall, masking something and unmasking if it turns out to be stable is +safer (and leads to a better user experience) than the inverse (pushing +unmasked and breakage occurring). +</p> + +<p> +Entries are added chronologically <d/> that is, newer entries +should be placed towards the top of the file, underneath any initial +header comment block. </p> <p> diff --git a/profiles/packages/text.xml b/profiles/packages/text.xml index b8215f7..990a70b 100644 --- a/profiles/packages/text.xml +++ b/profiles/packages/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/packages/"> <chapter> <title>Profiles <c>packages</c> File</title> @@ -6,7 +6,7 @@ <p> The <c>packages</c> file in <c>profiles/</c> controls the packages pulled in by the -<c>system</c> target. The <c>base/packages</c> file must not be modified without +<c>@system</c> set. The <c>base/packages</c> file must not be modified without discussion on the <c>gentoo-dev</c> list; subprofile overrides are up to the relevant arch teams. </p> diff --git a/profiles/profiles.desc/text.xml b/profiles/profiles.desc/text.xml deleted file mode 100644 index 16dc52a..0000000 --- a/profiles/profiles.desc/text.xml +++ /dev/null @@ -1,14 +0,0 @@ -<?xml version="1.0"?> -<guide self="profiles/profiles.desc/"> -<chapter> -<title>Profiles <c>profiles.desc</c> File</title> -<body> - -<todo> -Find someone who knows exactly what this file's really used for with -current portage versions and what is and isn't allowed. -</todo> - -</body> -</chapter> -</guide> diff --git a/profiles/text.xml b/profiles/text.xml index 4db23c6..cf71673 100644 --- a/profiles/text.xml +++ b/profiles/text.xml @@ -1,12 +1,18 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/"> <chapter> <title>Profiles</title> <body> <p> -This section provides details on the <c>profiles/</c> directory. All of these files -are also documented in <c>man portage</c>. +This section provides details on the <c>profiles/</c> directory. All of these +files are also documented in <c>man portage</c>, but the canonical reference +for profiles is within +<uri link="https://projects.gentoo.org/pms/8/pms.html#x1-320004.4">PMS</uri>. +</p> + +<p> +Portage-specific behaviour must not be relied upon in the repository. </p> </body> @@ -20,9 +26,9 @@ are also documented in <c>man portage</c>. <include href="categories/"/> <include href="info_files/"/> +<include href="make.defaults/"/> <include href="package.mask/"/> <include href="packages/"/> -<include href="profiles.desc/"/> <include href="updates/"/> <include href="use.desc/"/> <include href="use.mask/"/> diff --git a/profiles/updates/text.xml b/profiles/updates/text.xml index ae859e4..ae102d3 100644 --- a/profiles/updates/text.xml +++ b/profiles/updates/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/updates/"> <chapter> <title>Profiles <c>updates/</c> Directory</title> @@ -36,10 +36,11 @@ the actual changes to the package have to be done manually. </tr> <tr> <ti> - <c>slotmove atom oldslot newslot</c> + <c>slotmove spec oldslot newslot</c> </ti> <ti> - Indicates that the atom specified has changed slots. + Indicates that the package matching dependency specification <c>spec</c> + has changed slots. </ti> </tr> </table> diff --git a/profiles/use.desc/text.xml b/profiles/use.desc/text.xml index 30c3a41..301c53e 100644 --- a/profiles/use.desc/text.xml +++ b/profiles/use.desc/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/use.desc/"> <chapter> <title>Profiles <c>use.desc</c> and <c>use.local.desc</c> Files</title> @@ -14,7 +14,7 @@ discussion on the <c>gentoo-dev</c> list. The <c>metadata.xml</c> file on each ebuild category contains a list of the local <c>USE</c> flags, together with short description for the package in the said category. More information about the <c>metadata.xml</c> file can be found -<uri link="ebuild-writing/misc-files/metadata/index.html">here.</uri> +<uri link="::ebuild-writing/misc-files/metadata/">here.</uri> </p> <note> @@ -26,7 +26,7 @@ so you must never edit it directly. Having a small number of packages using identically named local <c>USE</c> flags is allowed. If the number starts to grow substantially, it may be worth proposing that the flag becomes a global <d /> see -<uri link="::general-concepts/use-flags#Local and Global USE Flags"/>. +<uri link="::general-concepts/use-flags/#Local and Global USE Flags"/>. </p> <p> diff --git a/profiles/use.mask/text.xml b/profiles/use.mask/text.xml index be6242f..f3c080c 100644 --- a/profiles/use.mask/text.xml +++ b/profiles/use.mask/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/use.mask/"> <chapter> <title>Profiles <c>use.mask</c> File</title> @@ -11,9 +11,9 @@ particular profile. This can be useful for various reasons: <ul> <li> - Masking hardware-specific feature flags. For example, <c>mmx</c> and <c>sse</c> are - only available on x86, <c>altivec</c> is only available on <c>ppc</c> and <c>vis</c> is - only available on sparc v9. + Masking hardware-specific feature flags. For example, <c>mmx</c> and + <c>sse</c> are only available on <c>x86</c>, <c>altivec</c> is only + available on <c>ppc</c> and <c>vis</c> is only available on <c>sparc</c> v9. </li> <li> Disabling unavailable soft dependencies. A simple hypothetical example <d /> say @@ -32,7 +32,9 @@ defined purpose. </p> <p> -Updates to <c>use.mask</c> should be handled via the relevant arch team. +Updates to <c>use.mask</c> should be handled via the relevant arch team. Any +additions are sorted chronologically, starting at the top of the file +(underneath any comment header blocks). </p> <p> diff --git a/quickstart/text.xml b/quickstart/text.xml index 380b994..c66f4ac 100644 --- a/quickstart/text.xml +++ b/quickstart/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="quickstart/"> <chapter> <title>Quickstart Ebuild Guide</title> @@ -13,8 +13,9 @@ idea of how ebuilds work. </p> <p> -For proper coverage of all the ins and outs, see <uri link="::ebuild-writing"/>. -The <uri link="::general-concepts"/> chapter will also be of use. +For proper coverage of all the ins and outs, +see <uri link="::ebuild-writing/"/>. +The <uri link="::general-concepts/"/> chapter will also be of use. </p> <p> @@ -34,29 +35,27 @@ can see real ebuilds in the main tree). </p> <codesample lang="ebuild"> -# Copyright 1999-2012 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -EAPI=4 +EAPI=8 DESCRIPTION="Exuberant ctags generates tags files for quick source navigation" -HOMEPAGE="http://ctags.sourceforge.net" +HOMEPAGE="https://ctags.io/ https://github.com/universal-ctags/ctags" SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz" -LICENSE="GPL-2" +LICENSE="GPL-2+" SLOT="0" KEYWORDS="~mips ~sparc ~x86" src_configure() { - econf --with-posix-regex + econf --with-posix-regex } src_install() { - emake DESTDIR="${D}" install + emake DESTDIR="${D}" install - dodoc FAQ NEWS README - dohtml EXTENDING.html ctags.html + dodoc FAQ NEWS README } </codesample> </body> @@ -75,8 +74,8 @@ At the top of the ebuild is a header block. This is present in all ebuilds. </p> <p> -Ebuilds are indented using tabs, with each tab representing four places. See -<uri link="::ebuild-writing/file-format"/>. +Ebuilds are indented using tabs, with each tab representing four places. +See <uri link="::ebuild-writing/file-format/"/>. </p> </body> </subsection> @@ -91,7 +90,7 @@ the ebuild and package in question. </p> <p> -The <c>EAPI</c> of the ebuild, see <uri link="::ebuild-writing/eapi"/>. +The <c>EAPI</c> of the ebuild, see <uri link="::ebuild-writing/eapi/"/>. </p> <p> @@ -101,32 +100,33 @@ of the package and its purpose. <p> The <c>HOMEPAGE</c> is a link to the package's homepage (remember to -include the <c>http://</c> part). +include the URI scheme, for example <c>https://</c>). </p> <p> The <c>SRC_URI</c> tells Portage the address to use for downloading the source tarball. Here, <c>mirror://sourceforge/</c> is a special -notation meaning "any of the Sourceforge mirrors". +notation meaning "any of the Sourceforge mirrors". <c>${P}</c> is a read-only variable set by Portage which is the package's name and version <d/> in this case, it would be <c>ctags-5.5.4</c>. </p> <p> -The <c>LICENSE</c> is <c>GPL-2</c> (the GNU General Public License version 2). +The <c>LICENSE</c> is <c>GPL-2+</c> (the GNU General Public License version 2 +or (at your option) any later version). </p> <p> -The <c>SLOT</c> variable tells Portage which slot this package installs to. If -you've not seen slots before, either just use <c>"0"</c> or read -<uri link="::general-concepts/slotting"/>. +The <c>SLOT</c> variable tells Portage which slot this package installs to. +If you've not seen slots before, either just use <c>"0"</c> or read +<uri link="::general-concepts/slotting/"/>. </p> <p> The <c>KEYWORDS</c> variable is set to archs upon which this ebuild has been tested. We use <c>~</c> keywords for newly written ebuilds <d/> packages are not -committed straight to stable, even if they seem to work. See <uri link="::keywording"/> for -details. +committed straight to stable, even if they seem to work. +See <uri link="::keywording/"/> for details. </p> </body> </subsection> @@ -148,26 +148,25 @@ The <c>src_install</c> function is called by Portage when it wants to <e>install</e> the package. A slight subtlety here <d/> rather than installing straight to the live filesystem, we must install to a special location which is given by the <c>${D}</c> variable (Portage sets -this <d/> see <uri link="::general-concepts/install-destinations"/> and -<uri link="::general-concepts/sandbox"/>). +this <d/> see <uri link="::general-concepts/install-destinations/"/> and +<uri link="::general-concepts/sandbox/"/>). </p> <note> -The canonical install method is <c>emake DESTDIR="${D}" -install</c>. This will work with any properly written standard -<c>Makefile</c>. If this gives sandbox errors, try <c>einstall</c> -instead. If this still fails, see <uri -link="::ebuild-writing/functions/src_install/"/> for how to do manual -installs. +The canonical install method is <c>emake DESTDIR="${D}" install</c>. This will +work with any properly written standard <c>Makefile</c>. If this gives sandbox +errors, see <uri link="::ebuild-writing/functions/src_install/"/> for how to do +manual installs. </note> <p> -The <c>dodoc</c> and <c>dohtml</c> are helper functions for installing +The <c>dodoc</c> is a helper function for installing files into the relevant part of <c>/usr/share/doc</c>. </p> <p> -Ebuilds can define other functions (see <uri link="::ebuild-writing/functions"/>). +Ebuilds can define other functions +(see <uri link="::ebuild-writing/functions/"/>). In all cases, Portage provides a reasonable default implementation which quite often does the 'right thing'. There was no need to define <c>src_unpack</c> and <c>src_compile</c> functions here, for example @@ -196,7 +195,7 @@ failed. <p> In the ctags example, we didn't tell Portage about any dependencies. As it happens, that's ok, because ctags only needs a basic toolchain to compile and -run (see <uri link="::general-concepts/dependencies#Implicit System Dependency"/> +run (see <uri link="::general-concepts/dependencies/#Implicit System Dependency"/> for why we don't need to depend upon those explicitly). However, life is rarely that simple. </p> @@ -206,11 +205,10 @@ Here's <c>app-misc/detox/detox-1.1.1.ebuild</c>: </p> <codesample lang="ebuild"> -# Copyright 1999-2012 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -EAPI=4 +EAPI=8 DESCRIPTION="detox safely removes spaces and strange characters from filenames" HOMEPAGE="http://detox.sourceforge.net/" @@ -222,16 +220,11 @@ KEYWORDS="~hppa ~mips sparc x86" RDEPEND="dev-libs/popt" DEPEND="${RDEPEND} - sys-devel/flex - sys-devel/bison" + sys-devel/flex" +BDEPEND="sys-devel/bison" src_configure() { - econf --with-popt -} - -src_install() { - emake DESTDIR="${D}" install - dodoc README CHANGES + econf --with-popt } </codesample> @@ -240,18 +233,22 @@ Again, you can see the ebuild header and the various informational variables. In <c>SRC_URI</c>, <c>${PN}</c> is used to get the package's name <e>without</e> the version suffix (there are more of these variables <d/> see -<uri link="::ebuild-writing/variables#Predefined Read-Only Variables"/>). +<uri link="::ebuild-writing/variables/#Predefined Read-Only Variables"/>). </p> <p> -Again, we define <c>src_configure</c> and <c>src_install</c> functions. +We define <c>src_configure</c> only. <c>src_install</c> does not need to +be defined since the default implementation calling <c>emake install</c> +and installing common documentation files works correctly for the package. </p> <p> -The <c>DEPEND</c> and <c>RDEPEND</c> variables are how Portage determines which -packages are needed to build and run the package. The <c>DEPEND</c> variable lists -compile-time dependencies, and the <c>RDEPEND</c> lists runtime dependencies. See -<uri link="::general-concepts/dependencies"/> for some more complex examples. +The <c>BDEPEND</c>, <c>DEPEND</c>, and <c>RDEPEND</c> variables are how Portage +determines which packages are needed to build and run the package. The +<c>BDEPEND</c> variable lists build-time (executable) dependencies, +<c>DEPEND</c> variable lists compile-time dependencies, and the <c>RDEPEND</c> +lists runtime dependencies. See <uri link="::general-concepts/dependencies/"/> +for some more complex examples. </p> </body> @@ -262,22 +259,17 @@ compile-time dependencies, and the <c>RDEPEND</c> lists runtime dependencies. Se <body> <p> -Often we need to apply patches. This is done in the <c>src_prepare</c> -function using the <c>epatch</c> helper function. To use <c>epatch</c> -one must first tell Portage that the <c>eutils</c> eclass (an eclass is -like a library) is required <d/> -this is done via <c>inherit eutils</c> at the top of the ebuild. Here's -<c>app-misc/detox/detox-1.1.0.ebuild</c>: +Often we need to apply patches. This is done either by defining the +<c>PATCHES</c> array in global scope or in the <c>src_prepare</c> function +using the <c>eapply</c> helper function. To use <c>eapply</c>, +one must use EAPI 7. Here's <c>app-misc/detox/detox-1.1.0.ebuild</c>: </p> <codesample lang="ebuild"> -# Copyright 1999-2012 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -EAPI=4 - -inherit eutils +EAPI=8 DESCRIPTION="detox safely removes spaces and strange characters from filenames" HOMEPAGE="http://detox.sourceforge.net/" @@ -289,31 +281,32 @@ KEYWORDS="~hppa ~mips ~sparc ~x86" RDEPEND="dev-libs/popt" DEPEND="${RDEPEND} - sys-devel/flex - sys-devel/bison" + sys-devel/flex" +BDEPEND="sys-devel/bison" src_prepare() { - epatch "${FILESDIR}"/${P}-destdir.patch \ - "${FILESDIR}"/${P}-parallel_build.patch + eapply "${FILESDIR}"/${P}-destdir.patch \ + "${FILESDIR}"/${P}-parallel_build.patch + eapply_user } src_configure() { - econf --with-popt -} - -src_install() { - emake DESTDIR="${D}" install - dodoc README CHANGES + econf --with-popt } </codesample> <p> Note the <c>${FILESDIR}/${P}-destdir.patch</c> <d/> this refers to <c>detox-1.1.0-destdir.patch</c>, which lives in the <c>files/</c> -subdirectory in the Portage tree. Larger patch files must go on your +subdirectory in the Gentoo repository. Larger patch files must go on your developer's space at <c>dev.gentoo.org</c> rather than in <c>files/</c> or -mirrors <d/> see <uri link="::general-concepts/mirrors#Gentoo Mirrors"/> and <uri -link="::ebuild-writing/functions/src_prepare/epatch/"/>. +mirrors <d/> see <uri link="::general-concepts/mirrors/#Gentoo Mirrors"/> and +<uri link="::ebuild-writing/functions/src_prepare/epatch/"/>. +</p> + +<p> +When the <c>src_prepare</c> phase is overridden, it must be ensured +that <c>eapply_user</c> is called. </p> </body> @@ -329,29 +322,25 @@ replacement iconv for <c>libc</c> implementations which don't have their own. </p> <codesample lang="ebuild"> -# Copyright 1999-2012 Gentoo Foundation +# Copyright 1999-2022 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -EAPI=4 +EAPI=8 DESCRIPTION="GNU charset conversion library for libc which doesn't implement it" -HOMEPAGE="http://www.gnu.org/software/libiconv/" +HOMEPAGE="https://www.gnu.org/software/libiconv/" SRC_URI="ftp://ftp.gnu.org/pub/gnu/libiconv/${P}.tar.gz" -LICENSE="LGPL-2.1" +LICENSE="LGPL-2+ GPL-3+" SLOT="0" KEYWORDS="~amd64 ~ppc ~sparc ~x86" IUSE="nls" -DEPEND="!sys-libs/glibc" +RDEPEND="!sys-libs/glibc" +DEPEND="${RDEPEND}" src_configure() { - econf $(use_enable nls) -} - -src_install() { - emake DESTDIR="${D}" install + econf $(use_enable nls) } </codesample> @@ -373,60 +362,59 @@ Another more complicated example, this time based upon </p> <codesample lang="ebuild"> -# Copyright 1999-2012 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -EAPI=4 +EAPI=8 -inherit eutils +inherit desktop DESCRIPTION="A lightweight email client and newsreader" -HOMEPAGE="http://sylpheed.good-day.net/" +HOMEPAGE="https://sylpheed.good-day.net/" SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2" -LICENSE="GPL-2" +LICENSE="GPL-2+ LGPL-2.1+" SLOT="0" -KEYWORDS="alpha amd64 hppa ia64 ppc ppc64 sparc x86" +KEYWORDS="~alpha amd64 hppa ~ia64 ppc ppc64 sparc x86" IUSE="crypt imlib ipv6 ldap nls pda ssl xface" RDEPEND="=x11-libs/gtk+-2* - crypt? ( >=app-crypt/gpgme-0.4.5 ) - imlib? ( media-libs/imlib2 ) - ldap? ( >=net-nds/openldap-2.0.11 ) - pda? ( app-pda/jpilot ) - ssl? ( dev-libs/openssl ) - xface? ( >=media-libs/compface-1.4 ) - app-misc/mime-types - x11-misc/shared-mime-info" -DEPEND="${RDEPEND} - dev-util/pkgconfig - nls? ( >=sys-devel/gettext-0.12.1 )" - -src_prepare() { - epatch "${FILESDIR}"/${PN}-namespace.diff \ - "${FILESDIR}"/${PN}-procmime.diff -} + crypt? ( >=app-crypt/gpgme-0.4.5 ) + imlib? ( media-libs/imlib2 ) + ldap? ( >=net-nds/openldap-2.0.11 ) + pda? ( app-pda/jpilot ) + ssl? ( dev-libs/openssl ) + xface? ( >=media-libs/compface-1.4 ) + app-misc/mime-types + x11-misc/shared-mime-info" +DEPEND="${RDEPEND}" +BDEPEND="dev-util/pkgconfig + nls? ( >=sys-devel/gettext-0.12.1 )" + +PATCHES=( + "${FILESDIR}"/${PN}-namespace.patch + "${FILESDIR}"/${PN}-procmime.patch +) src_configure() { - econf \ - $(use_enable nls) \ - $(use_enable ssl) \ - $(use_enable crypt gpgme) \ - $(use_enable pda jpilot) \ - $(use_enable ldap) \ - $(use_enable ipv6) \ - $(use_enable imlib) \ - $(use_enable xface compface) + econf \ + $(use_enable nls) \ + $(use_enable ssl) \ + $(use_enable crypt gpgme) \ + $(use_enable pda jpilot) \ + $(use_enable ldap) \ + $(use_enable ipv6) \ + $(use_enable imlib) \ + $(use_enable xface compface) } src_install() { - emake DESTDIR="${D}" install + emake DESTDIR="${D}" install - doicon sylpheed.png - domenu sylpheed.desktop + doicon sylpheed.png + domenu sylpheed.desktop - dodoc [A-Z][A-Z]* ChangeLog* + dodoc [A-Z][A-Z]* ChangeLog* } </codesample> diff --git a/search.js b/search.js new file mode 100644 index 0000000..c56a31a --- /dev/null +++ b/search.js @@ -0,0 +1,112 @@ +/* + * Copyright 2019 Gentoo Authors + * Distributed under the terms of the GNU GPL version 2 or later + */ +"use strict"; + +var search_index = null; +var search_input = document.getElementById("searchInput"); + +search_input.addEventListener("keyup", function(event) { + if(event.keyCode === 13) { + event.preventDefault(); + document.getElementById("mw-searchButton").click(); + } +}); + +function buildIndex() { + search_index = lunr(function () { + this.ref('id'); + this.field('text'); + this.metadataWhitelist = ['position'] + + documents.forEach(function (doc) { + this.add(doc); + }, this); + }); +} + +function fetchDocuments() { + document.getElementsByName("search")[0].onclick = null; + if (search_index == null) { + const script = document.createElement('script') + script.src = documentsSrc; + script.async = false; + script.onload = function() { + buildIndex(); + } + document.body.appendChild(script); + } +} + +function getContents(docs, uid) { + var contents = { name: "", text: "", url: "" }; + + contents.name = docs[uid].name; + contents.text = docs[uid].text; + contents.url = docs[uid].url; + + return contents; +} + +function escapeHTML(str) { + return str.replace(/[&<"']/g, function(m) { + switch (m) { + case '&': + return '&'; + case '<': + return '<'; + case '"': + return '"'; + default: + return '''; + } + }); +}; + +function search() { + var term = document.getElementById("searchInput").value; + if (term !== "") { + var results = search_index.search(term); + if (results.length > 0) { + $("#searchResults .modal-body").empty(); + $.each(results, function(index, result) { + var uid = result.ref; + var contents = getContents(documents, uid); + var stems = Object.keys(result.matchData.metadata); + var positions = []; + var text = ""; + var pos = 0; + + stems.forEach(function (stem) { + positions = positions.concat(result.matchData.metadata[stem].text.position); + }); + positions.sort(function(x, y) { + if (x[0] < y[0]) { return -1; } + else if (x[0] > y[0]) { return 1; } + else { return 0; } + }); + + for (var i = 0; i < positions.length; i++) { + text += escapeHTML(contents.text.substring(pos, positions[i][0])); + pos = positions[i][0]; + text += "<span style='background-color: yellow;'>"; + text += escapeHTML(contents.text.substring(pos, pos + positions[i][1])); + pos += positions[i][1]; + text += "</span>"; + } + text += escapeHTML(contents.text.substring(pos)); + + $("#searchResults .modal-body").append(`<article><h5><a href="${contents.url}"> + ${contents.name}</a></h5><p>${text}</p></article>`); + }); + } else { + $("#searchResults .modal-body").empty(); + $("#searchResults .modal-body").append("<p>No results found.</p>"); + } + } else { + $("#searchResults .modal-body").empty(); + $("#searchResults .modal-body").append("<p>No search term defined.</p>"); + } + $("#searchResults").modal(); +} diff --git a/tasks-reference/completion/text.xml b/tasks-reference/completion/text.xml index 5d31211..ded0ff9 100644 --- a/tasks-reference/completion/text.xml +++ b/tasks-reference/completion/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tasks-reference/completion/"> <chapter> <title>Completion Files</title> @@ -7,9 +7,11 @@ <p> Since v2.05a, <c>bash</c> has offered intelligent programmable completion. Writing such completions for your own programs/things you maintain is relatively easy -provided you know bash already. See <uri link="::eclass-reference/bash-completion.eclass/">bash-completion.eclass</uri> +provided you know bash already. See +<uri link="::eclass-reference/bash-completion-r1.eclass/"/> for how to install completion files. </p> +</body> <section> <title>Completion-Related Internal Bash Variables</title> @@ -162,20 +164,20 @@ the following can be used as a template for creating new completion functions: <codesample lang="ebuild" numbering="lines"> _foo() { - local cur prev opts - COMPREPLY=() - cur="${COMP_WORDS[COMP_CWORD]}" - prev="${COMP_WORDS[COMP_CWORD-1]}" - opts="" + local cur prev opts + COMPREPLY=() + cur="${COMP_WORDS[COMP_CWORD]}" + prev="${COMP_WORDS[COMP_CWORD-1]}" + opts="" - if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then - COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) - return 0 - fi + if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then + COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) + return 0 + fi - case "${prev}" in - # ... - esac + case "${prev}" in + # ... + esac } complete -F _foo foo </codesample> @@ -258,7 +260,7 @@ complete -F _foo foo If the test returns true, show the available options, <c>${opts}</c>. The -W option to <c>compgen</c> tells bash to complete on the word list (string or something that evaluates to a string). In the majority of cases, you'll - pass <c>'-- ${cur}'</c> to <c>compgen</c> telling it to only return those + pass <c>-- ${cur}</c> to <c>compgen</c> telling it to only return those completions that match <c>${cur}</c>. </ti> </tr> @@ -270,12 +272,13 @@ complete -F _foo foo Most of the time, you'll want to perform a certain action if <c>${prev}</c> is equal to a certain option. For example, if <c>foo</c> has a --file option (and -f for short) that takes any kind file, you could do: - <codesample lang="ebuild"> +<codesample lang="ebuild"> case "${prev}" in - -f|--file) - COMPREPLY=( $(compgen -f ? ${cur}) ) - ;; -esac</codesample> + -f|--file) + COMPREPLY=( $(compgen -f ? ${cur}) ) + ;; +esac +</codesample> </ti> </tr> <tr> @@ -363,7 +366,7 @@ Lines 1-12 are pretty much the same as in the previous section. If <c>${prev}</c> is equal to <c>-X</c> or <c>--package-names</c>, call <c>_pkgname</c> (a function defined by <c>gentoo-bashcomp</c> that completes on package - names - it sets <c>${COMPREPLY}</c>, so we don't worry about + names <d/> it sets <c>${COMPREPLY}</c>, so we don't worry about that here). </ti> </tr> @@ -421,8 +424,5 @@ Lines 1-12 are pretty much the same as in the previous section. </body> </section> - -</body> </chapter> </guide> - diff --git a/tasks-reference/environment/text.xml b/tasks-reference/environment/text.xml index ff4c14c..dca5565 100644 --- a/tasks-reference/environment/text.xml +++ b/tasks-reference/environment/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tasks-reference/environment/"> <chapter> <title>Environment Files</title> diff --git a/tasks-reference/init-scripts/text.xml b/tasks-reference/init-scripts/text.xml index e76670c..883c3f8 100644 --- a/tasks-reference/init-scripts/text.xml +++ b/tasks-reference/init-scripts/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tasks-reference/init-scripts/"> <chapter> <title>Init Scripts</title> @@ -14,9 +14,17 @@ should be handled via entries in <c>/etc/conf.d</c> with the same filename <d /> </p> <p> +Please note that unlike ebuilds, init scripts for OpenRC are expected to be +POSIX-compliant and must therefore avoid e.g. Bash-specific tests and +constructs. +</p> + +<p> An overview of the Gentoo init system and how to write init scripts is available in the <uri link="https://wiki.gentoo.org/wiki/Handbook:X86/Working/Initscripts#Writing_initscripts"> -Writing Init Scripts section</uri>. +Writing Init Scripts section</uri> and in the +<uri link="https://github.com/OpenRC/openrc/blob/master/service-script-guide.md"> +OpenRC documentation</uri>. </p> </body> diff --git a/tasks-reference/pam/text.xml b/tasks-reference/pam/text.xml index aa71a04..9a5bf5c 100644 --- a/tasks-reference/pam/text.xml +++ b/tasks-reference/pam/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tasks-reference/pam/"> <chapter> <title>Working with PAM</title> @@ -7,7 +7,7 @@ <p> PAM (Pluggable Authentication Modules) is a mechanism which allows different applications to authenticate using various specified parameters, using for -example a passwd/shadow file, a Kerberos server, an LDAP server or an a NT +example a passwd/shadow file, a Kerberos server, an LDAP server, or an NT Domain server (using Samba). </p> @@ -16,14 +16,7 @@ With PAM, a program just needs to require authentication for a given login class (defined in a <c>pam.d</c> file), and PAM framework will take care of calling the modules which will provide authentication. </p> - -<p> -There are different PAM implementations. Gentoo Linux, by default, uses the -Linux-PAM implementation which is installed via <c>sys-libs/pam</c>; FreeBSD and -NetBSD (and hence Gentoo/FreeBSD) use OpenPAM, which is a minimal version. The -different implementations can provide different authentication modules, and can -differ in some details of the configuration. -</p> +</body> <section> <title>Structure of a <c>pamd</c> File</title> @@ -39,8 +32,7 @@ The statement is composed of 3 or 4 tokens: <li> The first token specifies the type of service for which the statement is done. There are four types: - </li> - <ul> + <ul> <li> <e>account</e>, which checks for validity of the user account. </li> @@ -56,12 +48,12 @@ The statement is composed of 3 or 4 tokens: mount/umount of home directories, executed both before starting and after closing the user session. </li> - </ul> + </ul> + </li> <li> The second token is the control that tells PAM how to behave with failures and success of the authentication for the module specified: - </li> - <ul> + <ul> <li> <e>requisite</e>, a failure results in the termination of the process. </li> @@ -78,7 +70,8 @@ The statement is composed of 3 or 4 tokens: not the only module present, in which case a success or a failure of it makes the authentication succeed or fail. </li> - </ul> + </ul> + </li> <li> The third token is the module to execute for that type of service; PAM modules are extensible and, as the name says, pluggable. The result is that there are @@ -88,7 +81,7 @@ The statement is composed of 3 or 4 tokens: the module, but this creates problems because not all the systems install the modules in the same place: Linux-PAM on Gentoo is generally set up to load them from <c>/lib/security</c>, but for example on AMD64 this become - <c>/lib64/security</c>, and on OpenPAM they are just in <c>/usr/lib(64)</c>. The + <c>/lib64/security</c>. The result is that providing the full path will lead to non-working <c>pamd</c> files, and the right way to handle this is just states the module name <d /> the PAM implementation will take care of finding the module. @@ -98,16 +91,6 @@ The statement is composed of 3 or 4 tokens: passed to the module. These are module-dependent. </li> </ul> - -<p> -As the number and the type of modules shipped with the implementation depends on -the implementations themselves (Linux-PAM provides a full working set of -modules, OpenPAM doesn't provide modules at all, and it's the operating system -which provides them, as FreeBSD or NetBSD do), there are just a few modules -which can be used directly in <c>pamd</c> files without the risk of providing a -non-working configuration file: -</p> - <ul> <li> <c>pam_deny.so</c>, <c>pam_permit.so</c> <d /> they just report a failure or a success @@ -132,7 +115,7 @@ non-working configuration file: <p> There are also other modules which can be used for more complex authentication -against a database (mysql or postgresql), against an LDAP directory or against +against a database (mysql or postgresql), against an LDAP directory, or against an NT domain (using samba). This is useful on thin or fat clients where the users have an unique login for all the machines. Another place where this is useful is a cluster of servers which needs to authenticate against a single @@ -162,25 +145,15 @@ completely non-portable. It is not used in all the implementations of Linux-PAM <p> A solution came when AltLinux developers added a new instruction for the control -token: <e>include</e>. That control token can be used on Linux-PAM 0.78 and on -OpenPAM to do the same as a <c>required pam_stack.so</c>, replacing the module name +token: <e>include</e>. That control token can be used since Linux-PAM 0.78 +to do the same as a <c>required pam_stack.so</c>, replacing the module name with the name of the login class to mimic. </p> <p> In this way, instead of loading a module which in turn reloads pam, the option is parsed directly by the PAM implementation which loads the other login class -and takes care of executing it, and the same syntax is valid on both Linux-PAM -and OpenPAM systems. -</p> - -<p> -New packages (and new versions of old packages) should then use the <c>include</c> -directive instead of <c>pam_stack.so</c> module, but to do that they need to depend -on a later version of <c>sys-libs/pam</c> or on <c>sys-libs/openpam</c> (note: openpam -is for now just on G/FreeBSD's project overlay) <d /> to resolve this, -<c>virtual/pam</c> is set up to add the right dependency for the use of the include -directive. +and takes care of executing it. </p> </body> @@ -263,7 +236,5 @@ directory. </body> </section> - -</body> </chapter> </guide> diff --git a/tasks-reference/perl-modules/text.xml b/tasks-reference/perl-modules/text.xml deleted file mode 100644 index 4510bf7..0000000 --- a/tasks-reference/perl-modules/text.xml +++ /dev/null @@ -1,19 +0,0 @@ -<?xml version="1.0"?> -<guide self="tasks-reference/perl-modules/"> -<chapter> -<title>Perl Modules</title> -<body> - -<p> -This section covers where and how Perl modules should be installed. This is for -Perl applications which use their own <c>.pm</c> files, <b>not</b> for CPAN things. -</p> - -<todo> -write me. see thread on -dev. -</todo> - -</body> -</chapter> -</guide> - diff --git a/tasks-reference/text.xml b/tasks-reference/text.xml index 8de23bb..30e6017 100644 --- a/tasks-reference/text.xml +++ b/tasks-reference/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tasks-reference/"> <chapter> <title>Tasks Reference</title> @@ -22,5 +22,4 @@ ebuilds. <include href="environment/"/> <include href="init-scripts/"/> <include href="pam/"/> -<include href="perl-modules/"/> </guide> @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide root="true"> <chapter> <title>Master Index</title> @@ -10,15 +10,16 @@ inaccuracies, omissions, typos and the occasional outright lie. The intent is to make a handbook giving developers and users correct, detailed, up to date technical content. </p> + +<authors> + <authorlist title="Contributors" href="appendices/contributors/"/> +</authors> + <p> -Contributions are encouraged. See the <uri link="::appendices/contributing"/> -section for how to get started. If you have any corrections, suggestions or -improvements please look at the <uri link="https://bugs.gentoo.org/buglist.cgi?product=Doc%20Other;component=Devmanual;resolution=---">bug list</uri> -and file a <uri link="https://bugs.gentoo.org/enter_bug.cgi?product=Doc%20Other;component=Devmanual;format=guided">new bug</uri>. -The <uri link="::appendices/contributors"/> +Contributions are encouraged. See the <uri link="::appendices/contributing/"/> +section for how to get started. The <uri link="::appendices/contributors/"/> section lists specific contributions to this manual. </p> -<p>Users that are interested in becoming a Gentoo Developer are encouraged to also read the <uri link="http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml">Gentoo Developer Handbook</uri>.</p> </body> <section> @@ -39,12 +40,13 @@ section lists specific contributions to this manual. <include href="quickstart/"/> <include href="general-concepts/"/> <include href="ebuild-writing/"/> +<include href="ebuild-maintenance/" /> <include href="eclass-writing/"/> <include href="profiles/"/> <include href="keywording/"/> <include href="tasks-reference/"/> <include href="function-reference/"/> -<!-- <include href="eclass-reference/"/> --> +<include href="eclass-reference/"/> <include href="tools-reference/"/> <include href="hosted-projects/"/> <include href="archs/"/> diff --git a/tools-reference/bash/text.xml b/tools-reference/bash/text.xml index 053f6c3..76a7da0 100644 --- a/tools-reference/bash/text.xml +++ b/tools-reference/bash/text.xml @@ -1,17 +1,17 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/bash/"> <chapter> -<title><c>bash</c> -- Standard Shell</title> +<title><c>bash</c> — Standard Shell</title> <body> <p> A thorough understanding of <c>bash</c> programming is vital when working with ebuilds. </p> +</body> <section> <title>Bash Conditionals</title> -<body> <subsection> <title>Basic Selection</title> @@ -23,7 +23,7 @@ The basic conditional operator is the <c>if</c> statement: <codesample lang="ebuild"> if something ; then - do_stuff + do_stuff fi </codesample> @@ -40,13 +40,13 @@ Multiple pronged selection can be done using <c>else</c> and <c>elif</c>: <codesample lang="ebuild"> if something ; then - do_stuff + do_stuff elif something_else ; then - do_other_stuff + do_other_stuff elif full_moon ; then - howl + howl else - turn_into_a_newt + turn_into_a_newt fi </codesample> @@ -57,10 +57,10 @@ following will <b>not</b> work: <codesample lang="ebuild"> if some_stuff ; then - # A statement is required here. a blank or a comment - # isn't enough! + # A statement is required here. a blank or a comment + # isn't enough! else - einfo "Not some stuff" + einfo "Not some stuff" fi </codesample> @@ -71,10 +71,10 @@ If you really don't want to restructure the block, you can use a single colon <codesample lang="ebuild"> if some_stuff ; then - # Do nothing - : + # Do nothing + : else - einfo "Not some stuff" + einfo "Not some stuff" fi </codesample> @@ -86,24 +86,24 @@ fi <body> <p> -To do comparisons or file attribute tests, <c>[ ]</c> or <c>[[ ]]</c> blocks are -needed. +To do comparisons or file attribute tests, <c>[[ ]]</c> (preferred) or +<c>[ ]</c> blocks are needed. </p> <codesample lang="ebuild"> -# is $foo zero length? -if [[ -z "${foo}" ]] ; then - die "Please set foo" +# is ${foo} zero length? +if [[ -z ${foo} ]] ; then + die "Please set foo" fi -# is $foo equal to "moo"? -if [[ "${foo}" == "moo" ]] ; then - einfo "Hello Larry" +# is ${foo} equal to "moo"? +if [[ ${foo} == "moo" ]] ; then + einfo "Hello Larry" fi -# does "${ROOT}/etc/deleteme" exist? -if [[ -f "${ROOT}/etc/deleteme" ]] ; then - einfo "Please delete ${ROOT}/etc/readme manually!" +# does ${ROOT}/etc/deleteme exist? +if [[ -f ${ROOT}/etc/deleteme ]] ; then + einfo "Please delete ${ROOT}/etc/deleteme manually!" fi </codesample> @@ -120,15 +120,23 @@ all new code. </important> <p> +POSIX compliance is not a concern for ebuilds, as their interpreter is +guaranteed to be GNU Bash. POSIX style tests have different semantics and +using the common forms of tests adheres to the principle of least surprise. +Most developers will be used to Bash test semantics and behaviour and deviating +from this in ebuilds may be confusing. +</p> + +<p> This is because <c>[[ ]]</c> is a bash syntax construct, whereas <c>[ ]</c> is a -program which happens to be implemented as an internal -- as such, cleaner +program which happens to be implemented as an internal <d/> as such, cleaner syntax is possible with the former. For a simple illustration, consider: </p> <codesample lang="ebuild"> -bash$ [ -n $foo ] && [ -z $foo ] && echo "huh?" +bash$ [ -n ${foo} ] && [ -z ${foo} ] && echo "huh?" huh? -bash$ [[ -n $foo ]] && [[ -z $foo ]] && echo "huh?" +bash$ [[ -n ${foo} ]] && [[ -z ${foo} ]] && echo "huh?" bash$ </codesample> @@ -145,54 +153,30 @@ following are available: </p> <table> - <tr> - <th> - Operator - </th> - <th> - Purpose - </th> - </tr> - <tr> - <ti> - <c>==</c> (also <c>=</c>) - </ti> - <ti> - String equality - </ti> - </tr> - <tr> - <ti> - <c>!=</c> - </ti> - <ti> - String inequality - </ti> - </tr> - <tr> - <ti> - <c><</c> - </ti> - <ti> - String lexiographic comparison (before) - </ti> - </tr> - <tr> - <ti> - <c>></c> - </ti> - <ti> - String lexiographic comparison (after) - </ti> - </tr> - <tr> - <ti> - <c>=~</c> - </ti> - <ti> - String regular expression match (<b>bash 3 only</b>, not currently allowed in ebuilds) - </ti> - </tr> +<tr> + <th>Operator</th> + <th>Purpose</th> +</tr> +<tr> + <ti><c>==</c> (also <c>=</c>)</ti> + <ti>String equality</ti> +</tr> +<tr> + <ti><c>!=</c></ti> + <ti>String inequality</ti> +</tr> +<tr> + <ti><c><</c></ti> + <ti>String lexicographic comparison (before)</ti> +</tr> +<tr> + <ti><c>></c></ti> + <ti>String lexicographic comparison (after)</ti> +</tr> +<tr> + <ti><c>=~</c></ti> + <ti>String regular expression match</ti> +</tr> </table> </body> @@ -208,38 +192,20 @@ available: </p> <table> - <tr> - <th> - Operator - </th> - <th> - Purpose - </th> - </tr> - <tr> - <ti> - <c>-z "string"</c> - </ti> - <ti> - String has zero length - </ti> - </tr> - <tr> - <ti> - <c>-n "string"</c> - </ti> - <ti> - String has non-zero length - </ti> - </tr> +<tr> + <th>Operator</th> + <th>Purpose</th> +</tr> +<tr> + <ti><c>-z "string"</c></ti> + <ti>String has zero length</ti> +</tr> +<tr> + <ti><c>-n "string"</c></ti> + <ti>String has non-zero length</ti> +</tr> </table> -<note> -To check whether a variable is set and not blank, use <c>-n "${BLAH}"</c> -rather than <c>-n $BLAH</c>. The latter will cause problems in some situations if -the variable is unset. -</note> - </body> </subsection> @@ -253,62 +219,34 @@ following are available: </p> <table> - <tr> - <th> - Operator - </th> - <th> - Purpose - </th> - </tr> - <tr> - <ti> - <c>-eq</c> - </ti> - <ti> - Integer equality - </ti> - </tr> - <tr> - <ti> - <c>-ne</c> - </ti> - <ti> - Integer inequality - </ti> - </tr> - <tr> - <ti> - <c>-lt</c> - </ti> - <ti> - Integer less than - </ti> - </tr> - <tr> - <ti> - <c>-le</c> - </ti> - <ti> - Integer less than or equal to - </ti> - </tr> - <tr> - <ti> - <c>-gt</c> - </ti> - <ti> - Integer greater than - </ti> - </tr> - <tr> - <ti> - <c>-ge</c> - </ti> - <ti> - Integer greater than or equal to - </ti> - </tr> +<tr> + <th>Operator</th> + <th>Purpose</th> +</tr> +<tr> + <ti><c>-eq</c></ti> + <ti>Integer equality</ti> +</tr> +<tr> + <ti><c>-ne</c></ti> + <ti>Integer inequality</ti> +</tr> +<tr> + <ti><c>-lt</c></ti> + <ti>Integer less than</ti> +</tr> +<tr> + <ti><c>-le</c></ti> + <ti>Integer less than or equal to</ti> +</tr> +<tr> + <ti><c>-gt</c></ti> + <ti>Integer greater than</ti> +</tr> +<tr> + <ti><c>-ge</c></ti> + <ti>Integer greater than or equal to</ti> +</tr> </table> </body> @@ -324,182 +262,94 @@ available (lifted from <c>man bash</c>): </p> <table> - <tr> - <th> - Operator - </th> - <th> - Purpose - </th> - </tr> - <tr> - <ti> - <c>-a file</c> - </ti> - <ti> - Exists (use <c>-e</c> instead) - </ti> - </tr> - <tr> - <ti> - <c>-b file</c> - </ti> - <ti> - Exists and is a block special file - </ti> - </tr> - <tr> - <ti> - <c>-c file</c> - </ti> - <ti> - Exists and is a character special file - </ti> - </tr> - <tr> - <ti> - <c>-d file</c> - </ti> - <ti> - Exists and is a directory - </ti> - </tr> - <tr> - <ti> - <c>-e file</c> - </ti> - <ti> - Exists - </ti> - </tr> - <tr> - <ti> - <c>-f file</c> - </ti> - <ti> - Exists and is a regular file - </ti> - </tr> - <tr> - <ti> - <c>-g file</c> - </ti> - <ti> - Exists and is set-group-id - </ti> - </tr> - <tr> - <ti> - <c>-h file</c> - </ti> - <ti> - Exists and is a symbolic link - </ti> - </tr> - <tr> - <ti> - <c>-k file</c> - </ti> - <ti> - Exists and its sticky bit is set - </ti> - </tr> - <tr> - <ti> - <c>-p file</c> - </ti> - <ti> - Exists and is a named pipe (FIFO) - </ti> - </tr> - <tr> - <ti> - <c>-r file</c> - </ti> - <ti> - Exists and is readable - </ti> - </tr> - <tr> - <ti> - <c>-s file</c> - </ti> - <ti> - Exists and has a size greater than zero - </ti> - </tr> - <tr> - <ti> - <c>-t fd</c> - </ti> - <ti> - Descriptor fd is open and refers to a terminal - </ti> - </tr> - <tr> - <ti> - <c>-u file</c> - </ti> - <ti> - Exists and its set-user-id bit is set - </ti> - </tr> - <tr> - <ti> - <c>-w file</c> - </ti> - <ti> - Exists and is writable - </ti> - </tr> - <tr> - <ti> - <c>-x file</c> - </ti> - <ti> - Exists and is executable - </ti> - </tr> - <tr> - <ti> - <c>-O file</c> - </ti> - <ti> - Exists and is owned by the effective user id - </ti> - </tr> - <tr> - <ti> - <c>-G file</c> - </ti> - <ti> - Exists and is owned by the effective group id - </ti> - </tr> - <tr> - <ti> - <c>-L file</c> - </ti> - <ti> - Exists and is a symbolic link - </ti> - </tr> - <tr> - <ti> - <c>-S file</c> - </ti> - <ti> - Exists and is a socket - </ti> - </tr> - <tr> - <ti> - <c>-N file</c> - </ti> - <ti> - Exists and has been modified since it was last read - </ti> - </tr> +<tr> + <th>Operator</th> + <th>Purpose</th> +</tr> +<tr> + <ti><c>-a file</c></ti> + <ti>Exists (use <c>-e</c> instead)</ti> +</tr> +<tr> + <ti><c>-b file</c></ti> + <ti>Exists and is a block special file</ti> +</tr> +<tr> + <ti><c>-c file</c></ti> + <ti>Exists and is a character special file</ti> +</tr> +<tr> + <ti><c>-d file</c></ti> + <ti>Exists and is a directory</ti> +</tr> +<tr> + <ti><c>-e file</c></ti> + <ti>Exists</ti> +</tr> +<tr> + <ti><c>-f file</c></ti> + <ti>Exists and is a regular file</ti> +</tr> +<tr> + <ti><c>-g file</c></ti> + <ti>Exists and is set-group-id</ti> +</tr> +<tr> + <ti><c>-h file</c></ti> + <ti>Exists and is a symbolic link</ti> +</tr> +<tr> + <ti><c>-k file</c></ti> + <ti>Exists and its sticky bit is set</ti> +</tr> +<tr> + <ti><c>-p file</c></ti> + <ti>Exists and is a named pipe (FIFO)</ti> +</tr> +<tr> + <ti><c>-r file</c></ti> + <ti>Exists and is readable</ti> +</tr> +<tr> + <ti><c>-s file</c></ti> + <ti>Exists and has a size greater than zero</ti> +</tr> +<tr> + <ti><c>-t fd</c></ti> + <ti>Descriptor fd is open and refers to a terminal</ti> +</tr> +<tr> + <ti><c>-u file</c></ti> + <ti>Exists and its set-user-id bit is set</ti> +</tr> +<tr> + <ti><c>-w file</c></ti> + <ti>Exists and is writable</ti> +</tr> +<tr> + <ti><c>-x file</c></ti> + <ti>Exists and is executable</ti> +</tr> +<tr> + <ti><c>-O file</c></ti> + <ti>Exists and is owned by the effective user id</ti> +</tr> +<tr> + <ti><c>-G file</c></ti> + <ti>Exists and is owned by the effective group id</ti> +</tr> +<tr> + <ti><c>-L file</c></ti> + <ti>Exists and is a symbolic link</ti> +</tr> +<tr> + <ti><c>-S file</c></ti> + <ti>Exists and is a socket</ti> +</tr> +<tr> + <ti><c>-N file</c></ti> + <ti>Exists and has been modified since it was last read</ti> +</tr> </table> </body> @@ -510,46 +360,30 @@ available (lifted from <c>man bash</c>): <body> <p> -The general form of a file comparison is <c>"file1" -operator "file2"</c>. The -following are available (lifted from <c>man bash</c>): +The general form of a file comparison is <c>"file1" -operator "file2"</c>. +The following are available: </p> <table> - <tr> - <th> - Operator - </th> - <th> - Purpose - </th> - </tr> - <tr> - <ti> - <c>file1 -nt file2</c> - </ti> - <ti> - file1 is newer (according to modification date) than - file2, or if file1 exists and file2 does not. - </ti> - </tr> - <tr> - <ti> - <c>file1 -ot file2</c> - </ti> - <ti> - file1 is older than file2, or if file2 exists and - file1 does not. - </ti> - </tr> - <tr> - <ti> - <c>file1 -ef file2</c> - </ti> - <ti> - file1 and file2 refer to the same device and inode - numbers. - </ti> - </tr> +<tr> + <th>Operator</th> + <th>Purpose</th> +</tr> +<tr> + <ti><c>file1 -nt file2</c></ti> + <ti> + file1 is newer (according to modification date) than file2, + or file1 exists and file2 does not + </ti> +</tr> +<tr> + <ti><c>file1 -ot file2</c></ti> + <ti>file1 is older than file2, or file2 exists and file1 does not</ti> +</tr> +<tr> + <ti><c>file1 -ef file2</c></ti> + <ti>file1 is a hard link to file2</ti> +</tr> </table> </body> @@ -566,47 +400,32 @@ These are used <e>outside</e> of the <c>[[ ]]</c> blocks. For operator precedenc </p> <table> - <tr> - <th> - Construct - </th> - <th> - Effect - </th> - </tr> - <tr> - <ti> - <c>first || second</c> - </ti> - <ti> - first <e>or</e> second (short circuit) - </ti> - </tr> - <tr> - <ti> - <c> - first && second</c> - </ti> - <ti> - first <e>and</e> second (short circuit) - </ti> - </tr> - <tr> - <ti> - <c>! condition</c> - </ti> - <ti> - <e>not</e> condition - </ti> - </tr> +<tr> + <th>Construct</th> + <th>Effect</th> +</tr> +<tr> + <ti><c>first || second</c></ti> + <ti>first <e>or</e> second (short circuit)</ti> +</tr> +<tr> + <ti><c> +first && second</c></ti> + <ti>first <e>and</e> second (short circuit)</ti> +</tr> +<tr> + <ti><c>! condition</c></ti> + <ti><e>not</e> condition</ti> +</tr> </table> <note> These will also sometimes work <e>inside</e> <c>[[ ]]</c> constructs, and using -<c>!</c> before a test is fairly common. <c>[[ ! -f foo ]] && bar</c> is fine. However, -there are catches -- <c>[[ -f foo && bar ]]</c> will <b>not</b> work properly, since -commands cannot be run inside <c>[[ ]]</c> blocks. +<c>!</c> before a test is fairly common. <c>[[ ! -f foo ]] && bar</c> +is fine. However, there are catches <d/> <c>[[ -f foo && bar ]]</c> +will <b>not</b> work properly, since commands cannot be run inside <c>[[ ]]</c> +blocks. </note> <p> @@ -616,8 +435,6 @@ These should be avoided in favour of <c>[[ ]]</c> and the above operators. </body> </subsection> - -</body> </section> <section> @@ -632,7 +449,7 @@ task upon multiple items. <codesample lang="ebuild"> for myvar in "the first" "the second" "and the third" ; do - einfo "This is ${myvar}" + einfo "This is ${myvar}" done </codesample> @@ -643,7 +460,7 @@ event a given number of times. <codesample lang="ebuild"> for (( i = 1 ; i <= 10 ; i++ )) ; do - einfo "i is ${i}" + einfo "i is ${i}" done </codesample> @@ -654,7 +471,7 @@ ebuilds. <codesample lang="ebuild"> while hungry ; do - eat_cookies + eat_cookies done </codesample> @@ -664,7 +481,7 @@ This is most commonly used to iterate over lines in a file: <codesample lang="ebuild"> while read myline ; do - einfo "It says ${myline}" + einfo "It says ${myline}" done < some_file </codesample> @@ -687,6 +504,7 @@ manipulate or return information based upon variables. These can be used instead of expensive (or illegal, if we're in global scope) external calls to <c>sed</c> and friends. </p> +</body> <subsection> <title><c>bash</c> String Length</title> @@ -779,7 +597,7 @@ output (<c>stdout</c>) as a string. <note> The <c>`command`</c> construct also does this, but should be avoided in -favour of <c>$(command )</c> for clarity, ease of reading and nesting purposes. +favour of <c>$(command)</c> for clarity, ease of reading and nesting purposes. </note> <codesample lang="ebuild"> @@ -828,9 +646,9 @@ with the first match of <c>pattern</c> replaced with <c>replacement</c>. To repl <c>man bash</c> incorrectly describes what will be matched. Of all the possible leftmost matches, the longest will be taken. Yes, really, the longest, even if it involves favouring later groups or later branches. This is <b>not</b> like -<c>perl</c> or <c>sed</c>. See <uri -link="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap09.html#tag_09_01"> -IEEE1003.1-2004-9.1</uri> for details. +<c>perl</c> or <c>sed</c>. +See <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_01"> +IEEE Std 1003.1-2017, section 9.1</uri> for details. </note> <p> @@ -849,18 +667,65 @@ The <c>pattern</c> may contain a number of special metacharacters for pattern matching. </p> -<todo> -tables of bash metachars -</todo> +<table> +<tr> + <th>Character</th> + <th>Meaning</th> +</tr> +<tr> + <ti><c>*</c></ti> + <ti>Matches any string, including the null string</ti> +</tr> +<tr> + <ti><c>?</c></ti> + <ti>Matches any single character</ti> +</tr> +<tr> + <ti><c>[...]</c></ti> + <ti>Matches any one of the enclosed characters</ti> +</tr> +</table> + +<p> +Refer to the +<uri link="https://www.gnu.org/software/bash/manual/html_node/Pattern-Matching.html"> +Bash Reference Manual</uri> for further details and caveats regarding these +characters. +</p> <p> If the <c>extglob</c> shell option is enabled, a number of additional constructs -are available. These can be <e>extremely</e> useful sometimes. +are available. These can be <e>extremely</e> useful sometimes. In the following +table, a <c>pattern-list</c> is a list of one or more patterns separated by +<c>|</c>. </p> -<todo> -table of extra bash goodies -</todo> +<table> +<tr> + <th>Construct</th> + <th>Meaning</th> +</tr> +<tr> + <ti><c>?(pattern-list)</c></ti> + <ti>Matches zero or one occurrence of the given patterns</ti> +</tr> +<tr> + <ti><c>*(pattern-list)</c></ti> + <ti>Matches zero or more occurrences of the given patterns</ti> +</tr> +<tr> + <ti><c>+(pattern-list)</c></ti> + <ti>Matches one or more occurrences of the given patterns</ti> +</tr> +<tr> + <ti><c>@(pattern-list)</c></ti> + <ti>Matches one of the given patterns</ti> +</tr> +<tr> + <ti><c>!(pattern-list)</c></ti> + <ti>Matches anything except one of the given patterns</ti> +</tr> +</table> </body> </subsection> @@ -876,160 +741,88 @@ operators are supported (the table is in order of precedence, highest first): </p> <table> - <tr> - <th> - Operators - </th> - <th> - Effect - </th> - </tr> - <tr> - <ti> - <c>var++</c>, <c>var--</c> - </ti> - <ti> - Variable post-increment, post-decrement - </ti> - </tr> - <tr> - <ti> - <c>++var</c>, <c>--var</c> - </ti> - <ti> - Variable pre-increment, pre-decrement - </ti> - </tr> - <tr> - <ti> - <c>-</c>, <c>+</c> - </ti> - <ti> - Unary minus and plus - </ti> - </tr> - <tr> - <ti> - <c>!</c>, <c>~</c> - </ti> - <ti> - Logical negation, bitwise negation - </ti> - </tr> - <tr> - <ti> - <c>**</c> - </ti> - <ti> - Exponentiation - </ti> - </tr> - <tr> - <ti> - <c>*</c>, <c>/</c>, <c>%</c> - </ti> - <ti> - Multiplication, division, remainder - </ti> - </tr> - <tr> - <ti> - <c>+</c>, <c>-</c> - </ti> - <ti> - Addition, subtraction - </ti> - </tr> - <tr> - <ti> - <c><<</c>, <c>>></c> - </ti> - <ti> - Left, right bitwise shifts - </ti> - </tr> - <tr> - <ti> - <c><=</c>, <c>>=</c>, <c><</c>, <c>></c> - </ti> - <ti> - Comparison: less than or equal to, greater than or - equal to, strictly less than, strictly greater than - </ti> - </tr> - <tr> - <ti> - <c>==</c>, <c>!=</c> - </ti> - <ti> - Equality, inequality - </ti> - </tr> - <tr> - <ti> - <c>&</c> - </ti> - <ti> - Bitwise AND - </ti> - </tr> - <tr> - <ti> - <c>^</c> - </ti> - <ti> - Bitwise exclusive OR - </ti> - </tr> - <tr> - <ti> - <c>|</c> - </ti> - <ti> - Bitwise OR - </ti> - </tr> - <tr> - <ti> - <c>&&</c> - </ti> - <ti> - Logical AND - </ti> - </tr> - <tr> - <ti> - <c>||</c> - </ti> - <ti> - Logical OR - </ti> - </tr> - <tr> - <ti> - <c>expr ? expr : expr</c> - </ti> - <ti> - Conditional operator - </ti> - </tr> - <tr> - <ti> - <c>=</c>, <c>*=</c>, <c>/=</c>, <c>%=</c>, <c>+=</c>, <c>-=</c>, <c><<=</c>, - <c>>>=</c>, <c>&=</c>, <c>^=</c>, <c>|=</c> - </ti> - <ti> - Assignment - </ti> - </tr> - <tr> - <ti> - <c>expr1 , expr2</c> - </ti> - <ti> - Multiple statements - </ti> - </tr> +<tr> + <th>Operators</th> + <th>Effect</th> +</tr> +<tr> + <ti><c>var++</c>, <c>var--</c></ti> + <ti>Variable post-increment, post-decrement</ti> +</tr> +<tr> + <ti><c>++var</c>, <c>--var</c></ti> + <ti>Variable pre-increment, pre-decrement</ti> +</tr> +<tr> + <ti><c>-</c>, <c>+</c></ti> + <ti>Unary minus and plus</ti> +</tr> +<tr> + <ti><c>!</c>, <c>~</c></ti> + <ti>Logical negation, bitwise negation</ti> +</tr> +<tr> + <ti><c>**</c></ti> + <ti>Exponentiation</ti> +</tr> +<tr> + <ti><c>*</c>, <c>/</c>, <c>%</c></ti> + <ti>Multiplication, division, remainder</ti> +</tr> +<tr> + <ti><c>+</c>, <c>-</c></ti> + <ti>Addition, subtraction</ti> +</tr> +<tr> + <ti><c><<</c>, <c>>></c></ti> + <ti>Left, right bitwise shifts</ti> +</tr> +<tr> + <ti><c><=</c>, <c>>=</c>, <c><</c>, <c>></c></ti> + <ti> + Comparison: less than or equal to, greater than or equal to, + strictly less than, strictly greater than + </ti> +</tr> +<tr> + <ti><c>==</c>, <c>!=</c></ti> + <ti>Equality, inequality</ti> +</tr> +<tr> + <ti><c>&</c></ti> + <ti>Bitwise AND</ti> +</tr> +<tr> + <ti><c>^</c></ti> + <ti>Bitwise exclusive OR</ti> +</tr> +<tr> + <ti><c>|</c></ti> + <ti>Bitwise OR</ti> +</tr> +<tr> + <ti><c>&&</c></ti> + <ti>Logical AND</ti> +</tr> +<tr> + <ti><c>||</c></ti> + <ti>Logical OR</ti> +</tr> +<tr> + <ti><c>expr ? expr : expr</c></ti> + <ti>Conditional operator</ti> +</tr> +<tr> + <ti> + <c>=</c>, <c>*=</c>, <c>/=</c>, <c>%=</c>, <c>+=</c>, <c>-=</c>, + <c><<=</c>, <c>>>=</c>, <c>&=</c>, <c>^=</c>, <c>|=</c> + </ti> + <ti>Assignment</ti> +</tr> +<tr> + <ti><c>expr1 , expr2</c></ti> + <ti>Multiple statements</ti> +</tr> </table> <note> @@ -1038,10 +831,6 @@ There is no <c>**=</c> assignment operator. </body> </subsection> - -</body> </section> - -</body> </chapter> </guide> diff --git a/tools-reference/cat/text.xml b/tools-reference/cat/text.xml index 87ad905..c265fcc 100644 --- a/tools-reference/cat/text.xml +++ b/tools-reference/cat/text.xml @@ -1,13 +1,14 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/cat/"> <chapter> -<title><c>cat</c> -- File Concatenation</title> +<title><c>cat</c> — File Concatenation</title> <body> <p> The <c>cat</c> command can be used to concatenate the contents of two or more files. The usage is <c>cat firstfile secondfile ...</c>. </p> +</body> <section> <title>Abuse of <c>cat</c></title> @@ -50,12 +51,12 @@ On the other hand, <c>cat</c> is exceptionally useful for so-called <codesample lang="ebuild"> src_install() { - # ... - cat <<- EOF > "${D}/etc/mail/trusted-users" - # trusted-users - users that can send mail as others without a warning - # apache, mailman, majordomo, uucp are good candidates - EOF - # ... + # ... + cat <<- EOF > "${D}/etc/mail/trusted-users" || die + # trusted-users - users that can send mail as others without a warning + # apache, mailman, majordomo, uucp are good candidates + EOF + # ... } </codesample> @@ -80,7 +81,5 @@ desired effect. </p> </body> </section> - -</body> </chapter> </guide> diff --git a/tools-reference/cut/text.xml b/tools-reference/cut/text.xml index ccfd1e8..749f6fe 100644 --- a/tools-reference/cut/text.xml +++ b/tools-reference/cut/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/cut/"> <chapter> -<title><c>cut</c> -- Column Concatenation</title> +<title><c>cut</c> — Column Concatenation</title> <body> <p> @@ -44,7 +44,7 @@ could use: </p> <codesample lang="ebuild"> -cut -s -d',' -f2,4-5 input.txt > output.txt +cut -s -d , -f 2,4-5 input.txt > output.txt </codesample> <p> @@ -52,13 +52,13 @@ To chop the first character off stdin, one could use: </p> <codesample lang="ebuild"> -do_stuff | cut -c2- +do_stuff | cut -c 2- </codesample> <p> -See the cut manpage and -<uri link="http://www.opengroup.org/onlinepubs/000095399/utilities/cut.html"> -IEEE1003.1-2004-cut</uri> for full documentation. +See the <c>cut(1)</c> manpage and +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/cut.html"> +IEEE Std 1003.1-2017-cut</uri> for full documentation. </p> </body> diff --git a/tools-reference/diff-and-patch/text.xml b/tools-reference/diff-and-patch/text.xml index 1ea3bac..0e9755c 100644 --- a/tools-reference/diff-and-patch/text.xml +++ b/tools-reference/diff-and-patch/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/diff-and-patch/"> <chapter> -<title><c>diff and patch</c> -- File Differences</title> +<title><c>diff</c> and <c>patch</c> — File Differences</title> <body> <p> @@ -19,8 +19,9 @@ and <c>newfile</c>. To operate over directories instead, use <c>diff </p> <note> -<c>cvs</c> and <c>svn</c> provide <c>cvs diff</c> and <c>svn diff</c> -respectively which may be more helpful. +VCS like <c>git</c>,<c>svn</c> or <c>cvs</c> provide built-in diff +functionality (<c>git diff</c>, <c>svn diff</c>, <c>cvs diff</c>) +which may be more helpful. </note> <p> @@ -29,19 +30,21 @@ format. This is generally the best format to use when sending patches upstream too <d/> however, occasionally you may be asked to provide context diffs, which are more portable than unifieds (but don't handle conflicts as cleanly). In this case, use <c>-c</c> rather -than <c>-u</c>. +than <c>-u</c>. For a verbose guide into patches and patching, see +<uri link="::ebuild-writing/misc-files/patches/"/>. </p> <p> To apply a patch, use <c>patch -pX < whatever.patch</c>, where <c>X</c> is a number representing the number of path components which must be removed (typically this is <c>0</c> or <c>1</c>). Within -ebuilds, use the <c>epatch</c> function instead — see -<uri link="::ebuild-writing/functions/src_prepare/epatch"/>. +ebuilds, use the <c>epatch</c> function, or <c>eapply</c> function +beginning with EAPI=6, instead — see +<uri link="::ebuild-writing/functions/src_prepare/epatch/"/>. </p> <p> -The diff-1 and patch-1 manual pages provide more information. +The <c>diff(1)</c> and <c>patch(1)</c> manual pages provide more information. </p> </body> diff --git a/tools-reference/echangelog/text.xml b/tools-reference/echangelog/text.xml deleted file mode 100644 index 567dad9..0000000 --- a/tools-reference/echangelog/text.xml +++ /dev/null @@ -1,32 +0,0 @@ -<?xml version="1.0"?> -<guide self="tools-reference/echangelog/"> -<chapter> -<title><c>echangelog</c> -- ChangeLog Generation</title> -<body> - -<p> -The <c>echangelog</c> tool should be used to generate <uri link="::ebuild-writing/misc-files/changelog/">ChangeLog</uri> -entries. This tool uses the <c>ECHANGELOG_USER</c> environment -variable, which should be set in the format "Your Name -<user@gentoo.org>". The changelog message should be passed to -<c>echangelog</c> on the commandline, or otherwise <c>echangelog</c> -will open an editor for you to type your message. -</p> - -<p> -<c>echangelog</c> should be called <e>after</e> any adds, removes or -updates have been made. -</p> - -<p> -See echangelog-1 for details. -</p> - -<note> -The <c>echangelog</c> tool is considered deprecated as <c>repoman commit -m "[your message here]"</c> - will create a ChangeLog entry automatically when used for commits in the portage tree. -</note> - -</body> -</chapter> -</guide> diff --git a/tools-reference/echo/text.xml b/tools-reference/echo/text.xml index b6da93a..fb36543 100644 --- a/tools-reference/echo/text.xml +++ b/tools-reference/echo/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/echo/"> <chapter> -<title><c>echo</c> -- Print Strings</title> +<title><c>echo</c> — Print Strings</title> <body> <p> @@ -9,6 +9,7 @@ The <c>echo</c> command can be used to print strings. The standard usage is <c>echo firstString secondString ...</c>. Also, it provides additional parameters for formatting of the output. </p> +</body> <section> <title>Abuse of <c>echo</c></title> @@ -19,7 +20,7 @@ reconsider. It is almost always unnecessary. </p> <p> -First of all, for printing messages in standard portage scripts, you +First of all, for printing messages in standard Portage scripts, you can use the <c>einfo</c>, and <c>eerror</c> functions along with their corresponding functions, <c>einfon</c>, <c>eerrorn</c>, etc, which are the same as the former, but they won't print the trailing newline @@ -85,12 +86,10 @@ use: <c>echo -e "first line\nsecond line\nthird line"</c>. <p> Other escape sequences and additional parameters for the <c>echo</c> -command are available in the bash man page. +command are available in the <c>bash(1)</c> man page. </p> </body> </section> - -</body> </chapter> </guide> diff --git a/tools-reference/ekeyword/text.xml b/tools-reference/ekeyword/text.xml index 6f8e49e..eeb2d7b 100644 --- a/tools-reference/ekeyword/text.xml +++ b/tools-reference/ekeyword/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/ekeyword/"> <chapter> -<title><c>ekeyword</c> -- Keywording</title> +<title><c>ekeyword</c> — Keywording</title> <body> <p> @@ -13,7 +13,7 @@ the form <c>sparc</c> (to mark stable), <c>~sparc</c> (to mark unstable), <c>-sparc</c> (to mark unavailable) and <c>^sparc</c> (to remove the sparc keyword). The special <c>all</c> keyword is useful when doing version bumps <d/> <c>ekeyword ~all foo-1.23.ebuild</c> -will drop all currently present keywords to unstable. See ekeyword-1 +will drop all currently present keywords to unstable. See <c>ekeyword(1)</c> for details. </p> diff --git a/tools-reference/false-and-true/text.xml b/tools-reference/false-and-true/text.xml index 2c1ad83..e06aefa 100644 --- a/tools-reference/false-and-true/text.xml +++ b/tools-reference/false-and-true/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/false-and-true/"> <chapter> -<title><c>false and true</c> -- Generating Return Codes</title> +<title><c>false</c> and <c>true</c> — Generating Return Codes</title> <body> <p> diff --git a/tools-reference/find/text.xml b/tools-reference/find/text.xml index 4172128..22fe6a2 100644 --- a/tools-reference/find/text.xml +++ b/tools-reference/find/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/find/"> <chapter> -<title><c>find</c> -- Finding Files</title> +<title><c>find</c> — Finding Files</title> <body> <p> @@ -112,39 +112,48 @@ Useful rules include: </ti> <ti>no, GNU and FBSD</ti> </tr> + <tr> + <ti><c>-print0</c></ti> + <ti> + Separate file names by a NUL character instead of a newline in + the output. This is useful for guarding against files which may + include a newline in their names. + </ti> + <ti>no, GNU and FBSD</ti> + </tr> </table> <note> -EAPI>=5 assumes GNU find, so it is safe to use GNU extensions in +EAPI>=5 assumes GNU find, so it is safe to use GNU extensions in ebuild context for those EAPIs. </note> <p> By default, <c>find</c> will echo a list of matching files to the -standard output. This can be used in a <c>while</c> loop: +standard output separated by newlines. It can be combined with a +<c>for</c> loop for a small number of files with no weird characters +and spaces in their names: </p> <codesample lang="ebuild"> -while read f ; do - einfo "Doing unholy things to ${f}" -done < <(find "${S}" -type f) +for f in $(find "${S}" -type f) ; do + einfo "Doing unholy things to ${f}" +done </codesample> <p> -Or a <c>for</c> loop (for small numbers of files): +The above loop may cause issues with files containing special +characters in their names. A better way is to run <c>find</c> with the +<c>-print0</c> option in a <c>while</c> loop (note the options passed +to <c>while</c> and <c>read</c> for changing the delimiter): </p> <codesample lang="ebuild"> -for f in $(find "${S}" -type f) ; do - einfo "Calling down holy vengance upon ${f}" -done +while IFS="" read -d $'\0' -r f ; do + einfo "Calling down holy vengance upon ${f}" +done < <(find "${S}" -type f -print0) </codesample> -<warning> -In both cases, files with weird characters or spaces in their names -may cause serious problems. -</warning> - <p> As an alternative you can use the <c>-exec</c> argument. Be careful with escaping to ensure that <c>bash</c> doesn't gobble up the special @@ -198,9 +207,9 @@ is not POSIX, see the table). </warning> <p> -See find-1 and -<uri link="http://www.opengroup.org/onlinepubs/000095399/utilities/find.html"> -IEEE1003.1-2004-find</uri> for further details and examples. +See <c>find(1)</c> and +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/find.html"> +IEEE Std 1003.1-2017-find</uri> for further details and examples. </p> </body> diff --git a/tools-reference/grep/text.xml b/tools-reference/grep/text.xml index 5958588..2bf0075 100644 --- a/tools-reference/grep/text.xml +++ b/tools-reference/grep/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/grep/"> <chapter> -<title><c>grep</c> -- Text Filtering</title> +<title><c>grep</c> — Text Filtering</title> <body> <p> @@ -14,15 +14,15 @@ expression matches any line in a file. The usage is <c>grep "pattern" files</c>. If no files are specified, text is read from the standard input. The <c>pattern</c> is a standard basic regular expression, as described in -<uri link="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap09.html#tag_09_03"> -IEEE1003.1-2004-9.3</uri>. +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03"> +IEEE Std 1003.1-2017, section 9.3</uri>. </p> <p> If the <c>-E</c> argument is supplied, <c>pattern</c> is treated as being an extended regular expression as described in -<uri link="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap09.html#tag_09_04"> -IEEE1003.1-2004-9.4</uri>. +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04"> +IEEE Std 1003.1-2017, section 9.4</uri>. </p> <p> @@ -54,9 +54,9 @@ of <c>1</c> indicates no matches. </p> <p> -See <uri link="http://www.opengroup.org/onlinepubs/000095399/utilities/grep.html"> -IEEE1003.1-2004-grep</uri> for details. The grep-1 manual page on GNU -systems documents many non-portable additional features. +See <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/grep.html"> +IEEE Std 1003.1-2017-grep</uri> for details. The <c>grep(1)</c> manual page on +GNU systems documents many non-portable additional features. </p> </body> diff --git a/tools-reference/head-and-tail/text.xml b/tools-reference/head-and-tail/text.xml index 8e9db88..bed5dc3 100644 --- a/tools-reference/head-and-tail/text.xml +++ b/tools-reference/head-and-tail/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/head-and-tail/"> <chapter> -<title><c>head-and-tail</c> -- Line Extraction</title> +<title><c>head</c> and <c>tail</c> — Line Extraction</title> <body> <p> @@ -21,9 +21,10 @@ Use of the GNU <c>-c</c> option is unportable and should be avoided. </warning> <p> -For full details, see <uri link="http://www.opengroup.org/onlinepubs/000095399/utilities/head.html"> -IEEE1003.1-2004-head</uri>. Note that head-1 on GNU systems describes -many non-portable options. +For full details, see +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/head.html"> +IEEE Std 1003.1-2017-head</uri>. Note that <c>head(1)</c> on GNU systems +describes many non-portable options. </p> <p> @@ -32,22 +33,32 @@ file. The <c>-n</c> argument specifies how many lines to display. </p> <p> -To specify "the last five lines", use <c>tail -n5</c>. To specify "all -but the first five lines", use <c>tail -n+5</c>. +To specify "the last five lines", use <c>tail -n 5</c>. To specify "all +but the first five lines", use <c>tail -n +6</c>. </p> +<codesample lang="ebuild"> +# bad: drop first five lines, clumsily computing line count +tail -n $(($(wc -l in.txt | awk '{print $1}') - 5)) in.txt > out.txt + +# good: let tail count lines from the beginning of the file +tail -n +6 in.txt > out.txt +</codesample> + <warning> <c>head/tail -5</c> syntax is deprecated and not POSIX compliant. </warning> <p> -For full details, see <uri link="http://www.opengroup.org/onlinepubs/000095399/utilities/tail.html"> -IEEE1003.1-2004-tail</uri>. Note that tail-1 on GNU systems describes -many non-portable options. +For full details, see +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/tail.html"> +IEEE Std 1003.1-2017-tail</uri>. Note that <c>tail(1)</c> on GNU systems +describes many non-portable options. </p> +</body> <section> -<title>Chaining with <c>head</c> or <c>tail</c> with <c>sed</c></title> +<title>Chaining <c>head</c> or <c>tail</c> with <c>sed</c></title> <body> <p> Chaining <c>head</c> or <c>tail</c> with <c>sed</c> is usually @@ -97,6 +108,5 @@ sed -n -e '123p' </body> </section> -</body> </chapter> </guide> diff --git a/tools-reference/sed/text.xml b/tools-reference/sed/text.xml index 1b01b02..918a30e 100644 --- a/tools-reference/sed/text.xml +++ b/tools-reference/sed/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/sed/"> <chapter> -<title>sed -- Stream Editor</title> +<title>sed — Stream Editor</title> <body> <p> @@ -15,7 +15,7 @@ doing this is via <c>sed</c>: # This plugin is mapped to the 'h' key by default, which conflicts with some # other mappings. Change it to use 'H' instead. sed -i 's/\(noremap <buffer> \)h/\1H/' info.vim \ - || die 'sed failed' + || die 'sed failed' </codesample> <p> @@ -30,9 +30,9 @@ be set to <c>r0</c> if we don't have a <c>-r</c> component in our version. # for the line in version.h.in which contains "__fluxbox_version" and append # our content to it. if [[ "${PR}" == "r0" ]] ; then - suffix="gentoo" + suffix="gentoo" else - suffix="gentoo-${PR}" + suffix="gentoo-${PR}" fi sed -i \ -e "s~\(__fluxbox_version .@VERSION@\)~\1-${suffix}~" \ @@ -50,11 +50,11 @@ from the plugin files and convert it to Vim help format. # problems for us during the unmerge. Fortunately, sed can fix this # for us. First, we extract the documentation: sed -e '1,/^" HelpExtractorDoc:$/d' \ - "${S}"/plugin/ZoomWin.vim > ${S}/doc/ZoomWin.txt \ - || die "help extraction failed" + "${S}"/plugin/ZoomWin.vim > ${S}/doc/ZoomWin.txt \ + || die "help extraction failed" # Then we remove the help extraction code from the plugin file: sed -i -e '/^" HelpExtractor:$/,$d' "${S}"/plugin/ZoomWin.vim \ - || die "help extract remove failed" + || die "help extract remove failed" </codesample> <p> @@ -62,10 +62,12 @@ A summary of the more common ways of using <c>sed</c> and a description of commonly used address and token patterns follows. Note that some of these constructs are specific to <c>GNU sed 4</c> <d/> on non-GNU userland archs, the <c>sed</c> command must be aliased to GNU sed. Also note that <c>GNU sed 4</c> is -guaranteed to be installed as part of <c>system</c>. This was not always the case, +guaranteed to be installed as part of <c>@system</c>. This was not +always the case, which is why some packages, particularly those which use <c>sed -i</c>, have -<c>DEPEND</c> s upon <c>>=sys-apps/sed-4</c>. +a <c>DEPEND</c> upon <c>>=sys-apps/sed-4</c>. </p> +</body> <section> <title>Basic <c>sed</c> Invocation</title> @@ -77,11 +79,11 @@ The basic form of a call is: <codesample lang="ebuild"> sed [ option flags ] \ - -e 'first command' \ - -e 'second command' \ - -e 'and so on' \ - input-file > output-file \ - || die "Oops, sed didn't work!" + -e 'first command' \ + -e 'second command' \ + -e 'and so on' \ + input-file > output-file \ + || die "Oops, sed didn't work!" </codesample> <p> @@ -106,15 +108,15 @@ The term <e>pattern</e> refers to the description of text being matched. <body> <p> -The most common form of <c>sed</c> is to replace all instances of <c>"some text"</c> -with <c>"different content"</c>. This is done as follows: +The most common form of <c>sed</c> is to replace all instances of +<c>some text</c> with <c>different content</c>. This is done as follows: </p> <codesample lang="ebuild"> # replace all instances of "some text" with "different content" in # somefile.txt sed -i -e 's/some text/different content/g' somefile.txt || \ - die "Sed broke!" + die "Sed broke!" </codesample> <note> @@ -123,20 +125,25 @@ flag, only the first match on each line is replaced. </note> <warning> -The above will replace <c>"irksome texting"</c> with -<c>"irkdifferent contenting"</c>, which may not be desired. +The above will replace <c>irksome texting</c> with +<c>irkdifferent contenting</c>, which may not be desired. </warning> <p> If the pattern or the replacement string contains the forward slash character, it is usually easiest to use a different delimiter. Most punctuation characters -are allowed, although backslash and any form of brackets should be avoided. +are allowed, although backslash and any form of brackets should be avoided. You +should choose your delimiter <b>with care</b> to ensure it cannot appear in any +strings involved in the subject/replacement. For example, using <c>sed</c> with +CFLAGS is hazardous because it is user-supplied data (so may contain any +character), but one should in particular avoid e.g. +<uri link="https://bugs.gentoo.org/685160">the colon</uri> here. </p> <codesample lang="ebuild"> # replace all instances of "/usr/local" with "/usr" sed -i -e 's~/usr/local~/usr~g' somefile.txt || \ - die "sed broke" + die "sed broke" </codesample> <p> @@ -245,10 +252,11 @@ character 'a'. <note> At the time of writing, the <c>sed</c> documentation (<c>man sed</c> and <c>sed.info</c>) does not mention that POSIX character classes are supported. -Consult <uri -link="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap09.html#tag_09_03"> -IEEE1003.1-2004-9.3</uri> for full details of how these <e>should</e> work, and -the <c>sed</c> source code for full details of how these <e>actually</e> work. +Consult +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03"> +IEEE Std 1003.1-2017, section 9.3</uri> for full details of how these +<e>should</e> work, and the <c>sed</c> source code for full details of how +these <e>actually</e> work. </note> <p> @@ -414,7 +422,6 @@ the file, for example, causing your sed script to break. <section> <title>Regular Expression Atoms in <c>sed</c></title> -<body> <subsection> <title>Basic Atoms</title> @@ -771,8 +778,6 @@ Read the source, it's the only place these're documented properly... </body> </subsection> - -</body> </section> <section> @@ -888,17 +893,16 @@ write this <body> <p> -The author recommends <e>Mastering Regular Expressions</e> by Jeffrey E. F. Friedl -for those who wish to learn more about regexes. This text is remarkably devoid -of phrases like "let <c>t</c> be a finite contiguous sequence such that <c>t[n] ∈ ∑ -∀ n</c>", and was <e>not</e> written by someone whose pay cheque depended upon them being +The author recommends <uri link="::appendices/further-reading/#Books"> +<e>Mastering Regular Expressions</e> by Jeffrey E. F. Friedl</uri> for those who +wish to learn more about regexes. This text is remarkably devoid of phrases like +"let <c>t</c> be a finite contiguous sequence such that <c>t[n] ∈ ∑ ∀ n</c>", +and was <e>not</e> written by someone whose pay cheque depended upon them being able to express simple concepts with pages upon pages of mathematical and Greek symbols. </p> </body> </section> - -</body> </chapter> </guide> diff --git a/tools-reference/sort/text.xml b/tools-reference/sort/text.xml index ebbc69c..9f27c5b 100644 --- a/tools-reference/sort/text.xml +++ b/tools-reference/sort/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/sort/"> <chapter> -<title>sort -- Sorting Text</title> +<title>sort — Sorting Text</title> <body> <p> @@ -16,9 +16,9 @@ To ignore case, the <c>-f</c> switch may be used. </p> <p> -Many other options are available. See <c>man sort</c> and <uri -link="http://www.opengroup.org/onlinepubs/000095399/utilities/sort.html"> -IEEE1003.1-2004-sort</uri> for details. +Many other options are available. See <c>man sort</c> and +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/sort.html"> +IEEE Std 1003.1-2017-sort</uri> for details. </p> </body> diff --git a/tools-reference/text.xml b/tools-reference/text.xml index a4cadf8..b47e097 100644 --- a/tools-reference/text.xml +++ b/tools-reference/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/"> <chapter> <title>Tools Reference</title> @@ -9,6 +9,12 @@ This section provides an overview of various useful standard Unix and Gentoo tools and utilities that may be used within ebuilds or when working with ebuilds. </p> + +<p> +Please keep in mind the need for +<uri link="::ebuild-writing/error-handling/#The die Function">error handling</uri> +when using these tools in ebuilds. +</p> </body> <section> @@ -23,16 +29,12 @@ ebuilds. <include href="cat/"/> <include href="cut/"/> <include href="diff-and-patch/"/> -<include href="echangelog/"/> <include href="echo/"/> <include href="ekeyword/"/> <include href="false-and-true/"/> <include href="find/"/> <include href="grep/"/> <include href="head-and-tail/"/> -<!-- -<include href="repoman/"/> ---> <include href="sed/"/> <include href="sort/"/> <include href="tr/"/> diff --git a/tools-reference/tr/text.xml b/tools-reference/tr/text.xml index e7002e1..ca5001f 100644 --- a/tools-reference/tr/text.xml +++ b/tools-reference/tr/text.xml @@ -1,14 +1,14 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/tr/"> <chapter> -<title>tr -- Character Translation</title> +<title>tr — Character Translation</title> <body> <p> The <c>tr</c> command can be used to translate, squeeze and delete character -sequences. See <c>man tr</c> and <uri -link="http://www.opengroup.org/onlinepubs/000095399/utilities/tr.html"> -IEEE1003.1-2004-tr</uri> for the full specification. +sequences. See <c>man tr</c> and +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/tr.html"> +IEEE Std 1003.1-2017-tr</uri> for the full specification. </p> <note> @@ -26,27 +26,21 @@ and only writes to standard output. Therefore, you will have to use Deleting characters </dt> <dd> - <p> - To delete all occurrences of certain characters, use <c>tr -d asdf</c>. - </p> + To delete all occurrences of certain characters, use <c>tr -d asdf</c>. </dd> <dt> Deleting repeated characters </dt> <dd> - <p> - To replace repeated characters with a single character ('squeeze'), use - <c>tr -s asdf</c>. - </p> + To replace repeated characters with a single character ('squeeze'), use + <c>tr -s asdf</c>. </dd> <dt> Transliterating characters </dt> <dd> - <p> - To replace all 'a' characters with '1', all 'b' with '2' and all 'c' with - '3', use <c>tr abc 123</c>. - </p> + To replace all 'a' characters with '1', all 'b' with '2' and all 'c' with + '3', use <c>tr abc 123</c>. </dd> </dl> diff --git a/tools-reference/uniq/text.xml b/tools-reference/uniq/text.xml index 409fa44..39ecdfe 100644 --- a/tools-reference/uniq/text.xml +++ b/tools-reference/uniq/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/uniq/"> <chapter> -<title>uniq -- Filtering Duplicates</title> +<title>uniq — Filtering Duplicates</title> <body> <p> @@ -14,9 +14,9 @@ Instead of using <c>sort | uniq</c>, one should use <c>sort -u</c>. </note> <p> -See <c>man uniq</c> and <uri -link="http://www.opengroup.org/onlinepubs/000095399/utilities/uniq"> -IEEE1003.1-2004-uniq</uri> for details. +See <c>man uniq</c> and +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/uniq.html"> +IEEE Std 1003.1-2017-uniq</uri> for details. </p> </body> diff --git a/xsl/lang.highlight.c.xsl b/xsl/lang.highlight.c.xsl index d2d115e..f1e5937 100644 --- a/xsl/lang.highlight.c.xsl +++ b/xsl/lang.highlight.c.xsl @@ -1,3 +1,4 @@ +<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform' xmlns:str="http://exslt.org/strings" xmlns:exslt="http://exslt.org/common" @@ -32,6 +33,7 @@ <!-- Scan for quotes... --> <xsl:for-each select="exslt:node-set($tokenizedData)"> + <xsl:variable name="myPos" select="position()"/> <xsl:variable name="quotePos" select="count(../*[@delimiter='"' and position() < $myPos])"/> <xsl:variable name="commentOpen" select="count(str:tokenize_plasmaroo(substring-before($data, concat(' ', '/*'))))"/> <xsl:variable name="commentClosed" select="count(str:tokenize_plasmaroo(substring-before($data, concat(' ', '*/'))))"/> @@ -45,7 +47,7 @@ <xsl:choose> <!-- Highlight a quote --> <xsl:when test=". = '"'"> - <span class="Statement">"</span> + <span class="Statement">"</span> </xsl:when> <!-- If we're inside quotes stop here --> @@ -58,19 +60,24 @@ </span> </xsl:when> - <xsl:when test="$commentOpen != $commentClosed and position() > $commentOpen"> + <xsl:when test="$commentOpen != $commentClosed and position() > $commentOpen"> <span class="Comment"><xsl:value-of select="."/></span> </xsl:when> <!-- No match return --> <xsl:otherwise> <xsl:call-template name="lang.highlight.c.subtokenate"> - <xsl:with-param name="data" select="."/> - <xsl:with-param name="inPreProc" select="$macroLine"/> - </xsl:call-template> + <xsl:with-param name="data" select="."/> + <xsl:with-param name="inPreProc" select="$macroLine"/> + </xsl:call-template> </xsl:otherwise> </xsl:choose> </xsl:for-each> </xsl:template> </xsl:stylesheet> + +<!-- Local Variables: --> +<!-- indent-tabs-mode: nil --> +<!-- fill-column: 120 --> +<!-- End: --> diff --git a/xsl/lang.highlight.ebuild.xsl b/xsl/lang.highlight.ebuild.xsl index 4f84b8d..30ccc08 100644 --- a/xsl/lang.highlight.ebuild.xsl +++ b/xsl/lang.highlight.ebuild.xsl @@ -1,3 +1,4 @@ +<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform' xmlns:str="http://exslt.org/strings" xmlns:exslt="http://exslt.org/common" @@ -10,6 +11,96 @@ <xsl:variable name="lang.highlight.ebuild.variable-end">}</xsl:variable> <xsl:variable name="lang.highlight.ebuild.commentChar">#</xsl:variable> + <xsl:variable name="shell-keywords"> + ; if then fi -ge -lt -le -gt elif else eval unset sed rm cat [[ ]] while do read done make echo cd local return for + case esac in -n [ ] -z -f <<- > EOF + </xsl:variable> + + <xsl:variable name="pkg-mgr-keywords"> + <!-- Package manager commands in EAPI 0 (excluding commands banned in later EAPIs) --> + assert best_version debug-print debug-print-function debug-print-section die diropts dobin docinto doconfd dodir + dodoc doenvd doexe doinfo doinitd doins dolib.a dolib.so doman domo dosbin dosym ebegin econf eend eerror einfo + einfon elog emake ewarn exeinto exeopts EXPORT_FUNCTIONS fowners fperms has has_version inherit insinto insopts into + keepdir newbin newconfd newdoc newenvd newexe newinitd newins newlib.a newlib.so newman newsbin unpack use usev + use_enable use_with + <!-- EAPI 4 --> + docompress nonfatal + <!-- EAPI 5 --> + doheader newheader usex + <!-- EAPI 6 --> + eapply eapply_user einstalldocs get_libdir in_iuse + <!-- EAPI 7 --> + dostrip eqawarn ver_cut ver_rs ver_test + <!-- EAPI 8: no new commands --> + <!-- Sandbox --> + adddeny addpredict addread addwrite + <!-- Phase functions --> + pkg_pretend pkg_setup pkg_preinst pkg_postinst pkg_prerm pkg_postrm pkg_config pkg_info pkg_nofetch src_unpack + src_prepare src_configure src_compile src_test src_install + <!-- Default phase functions --> + default default_pkg_nofetch default_src_unpack default_src_prepare default_src_configure default_src_compile + default_src_test default_src_install + </xsl:variable> + + <xsl:variable name="eclass-keywords"> + <!-- autotools --> + autotools_check_macro autotools_m4dir_include autotools_m4sysdir_include config_rpath_update eaclocal + eaclocal_amflags eautoconf eautoheader eautomake eautopoint eautoreconf + <!-- bash-completion-r1 --> + bashcomp_alias dobashcomp get_bashcompdir newbashcomp + <!-- cmake --> + cmake_build cmake_comment_add_subdirectory cmake_run_in cmake_src_compile cmake_src_configure cmake_src_install + cmake_src_prepare cmake_src_test cmake_use_find_package + <!-- desktop --> + doicon domenu make_desktop_entry make_session_desktop newicon newmenu + <!-- epatch --> + epatch + <!-- flag-o-matic --> + all-flag-vars append-atomic-flags append-cflags append-cppflags append-cxxflags append-fflags append-flags + append-ldflags append-lfs-flags append-libs filter-flags filter-ldflags filter-lfs-flags filter-lto filter-mfpmath + get-flag is-flag is-flagq is-ldflag is-ldflagq no-as-needed raw-ldflags replace-cpu-flags replace-flags + replace-sparc64-flags strip-flags strip-unsupported-flags test-compile test-flag-CC test-flag-CCLD test-flag-CXX + test-flag-F77 test-flag-FC test-flags test-flags-CC test-flags-CCLD test-flags-CXX test-flags-F77 test-flags-FC + test_version_info + <!-- git-r3 --> + git-r3_checkout git-r3_fetch git-r3_peek_remote_ref git-r3_pkg_needrebuild git-r3_src_fetch git-r3_src_unpack + pkg_needrebuild + <!-- meson --> + meson_feature meson_install meson_src_compile meson_src_configure meson_src_install meson_src_test meson_use + <!-- multilib --> + get_abi_CFLAGS get_abi_CHOST get_abi_CTARGET get_abi_FAKE_TARGETS get_abi_LDFLAGS get_abi_LIBDIR get_all_abis + get_all_libdirs get_exeext get_install_abis get_libname get_modname has_multilib_profile is_final_abi multilib_env + multilib_toolchain_setup number_abis + <!-- ninja-utils --> + eninja get_NINJAOPTS + <!-- readme.gentoo-r1 --> + readme.gentoo_create_doc readme.gentoo_print_elog + <!-- rpm --> + rpm_spec_epatch rpm_src_unpack rpm_unpack srcrpm_unpack + <!-- toolchain-funcs --> + clang-fullversion clang-major-version clang-micro-version clang-minor-version clang-version econf_build + gcc-fullversion gcc-major-version gcc-micro-version gcc-minor-version gcc-specs-directive gcc-specs-nostrict + gcc-specs-now gcc-specs-pie gcc-specs-relro gcc-specs-ssp gcc-specs-ssp-to-all gcc-specs-stack-check gcc-version + gen_usr_ldscript tc-arch tc-arch-kernel tc-check-openmp tc-cpp-is-true tc-detect-is-softfloat + tc-enables-cxx-assertions tc-enables-fortify-source tc-enables-pie tc-enables-ssp tc-enables-ssp-all + tc-enables-ssp-strong tc-endian tc-env_build tc-export tc-export_build_env tc-get-c-rtlib tc-get-compiler-type + tc-get-cxx-stdlib tc-getAR tc-getAS tc-getBUILD_AR tc-getBUILD_AS tc-getBUILD_CC tc-getBUILD_CPP tc-getBUILD_CXX + tc-getBUILD_LD tc-getBUILD_NM tc-getBUILD_OBJCOPY tc-getBUILD_PKG_CONFIG tc-getBUILD_PROG tc-getBUILD_RANLIB + tc-getBUILD_READELF tc-getBUILD_STRINGS tc-getBUILD_STRIP tc-getCC tc-getCPP tc-getCXX tc-getDLLWRAP tc-getF77 + tc-getFC tc-getGCJ tc-getGO tc-getLD tc-getNM tc-getOBJCOPY tc-getOBJDUMP tc-getPKG_CONFIG tc-getPROG tc-getRANLIB + tc-getRC tc-getREADELF tc-getSTRINGS tc-getSTRIP tc-getTARGET_CPP tc-has-tls tc-is-clang tc-is-cross-compiler + tc-is-gcc tc-is-softfloat tc-is-static-only tc-ld-disable-gold tc-ld-force-bfd tc-ld-is-gold tc-ld-is-lld + tc-ninja_magic_to_arch tc-stack-grows-down tc-tuple-is-softfloat + <!-- user --> + enewgroup enewuser esetcomment esetgroups esethome esetshell + <!-- virtualx --> + virtx + <!-- xdg --> + xdg_pkg_postinst xdg_pkg_postrm xdg_pkg_preinst xdg_src_prepare + <!-- xdg-utils --> + xdg_desktop_database_update xdg_environment_reset xdg_icon_cache_update xdg_mimeinfo_database_update + </xsl:variable> + <xsl:template name="lang.highlight.ebuild.subtokenate"> <xsl:param name="data"/> <xsl:param name="nokeywords"/> @@ -32,23 +123,23 @@ </xsl:when> <xsl:when test="contains($data, '$(')"> - <xsl:call-template name="lang.highlight.ebuild.subtokenate"> - <xsl:with-param name="data" select="substring-before($data, '$(')"/> - </xsl:call-template> - <span class="PreProc">$(</span> - <xsl:call-template name="lang.highlight.ebuild.subtokenate"> - <xsl:with-param name="data" select="substring-after($data, '$(')"/> - </xsl:call-template> + <xsl:call-template name="lang.highlight.ebuild.subtokenate"> + <xsl:with-param name="data" select="substring-before($data, '$(')"/> + </xsl:call-template> + <span class="PreProc">$(</span> + <xsl:call-template name="lang.highlight.ebuild.subtokenate"> + <xsl:with-param name="data" select="substring-after($data, '$(')"/> + </xsl:call-template> </xsl:when> <xsl:when test="contains($data, '($(')"> - <xsl:call-template name="lang.highlight.ebuild.subtokenate"> - <xsl:with-param name="data" select="substring-before($data, '($(')"/> - </xsl:call-template> - <span class="PreProc">($(</span> - <xsl:call-template name="lang.highlight.ebuild.subtokenate"> - <xsl:with-param name="data" select="substring-after($data, '($(')"/> - </xsl:call-template> + <xsl:call-template name="lang.highlight.ebuild.subtokenate"> + <xsl:with-param name="data" select="substring-before($data, '($(')"/> + </xsl:call-template> + <span class="PreProc">($(</span> + <xsl:call-template name="lang.highlight.ebuild.subtokenate"> + <xsl:with-param name="data" select="substring-after($data, '($(')"/> + </xsl:call-template> </xsl:when> <xsl:when test="substring($data, string-length($data)) = ')' and not(contains($data, '('))"> @@ -59,7 +150,7 @@ </xsl:when> <xsl:when test="substring($data, 1, 1) = $lang.highlight.ebuild.qvariable-start"> - <span class="Identifier">$<xsl:value-of select="substring($data, 2)"/></span> + <span class="Identifier">$<xsl:value-of select="substring($data, 2)"/></span> </xsl:when> <xsl:when test="substring($data, 1, 1) = '(' and not(contains($data, ')'))"> @@ -75,9 +166,9 @@ <!-- Args --> <xsl:when test="contains($data, '--')"> - <xsl:call-template name="lang.highlight.ebuild.subtokenate"> - <xsl:with-param name="data" select="substring-before($data, '--')"/> - </xsl:call-template> + <xsl:call-template name="lang.highlight.ebuild.subtokenate"> + <xsl:with-param name="data" select="substring-before($data, '--')"/> + </xsl:call-template> <span class="PreProc">--</span> <xsl:variable name="cdata" select="substring-after($data, '--')"/> <xsl:choose> @@ -98,237 +189,20 @@ </xsl:choose> </xsl:when> - <!-- Functioney highlighing --> + <!-- Function highlighting --> <!-- sh grammar --> - <xsl:when test="$data = ';' or $data = 'if' or $data = 'then' or $data = 'fi' or $data = '-ge' or $data = '-lt' or $data = '-le' or - $data = '-gt' or $data = 'elif' or $data = 'else' or $data = 'eval' or $data = 'unset' or $data = 'sed' or - $data = 'rm' or $data = 'cat' or $data = '[[' or $data = ']]' or $data = 'while' or $data = 'do' or $data = 'read' or - $data = 'done' or $data = 'make' or $data = 'echo' or $data = 'cd' or $data = 'local' or $data = 'return' or - $data = 'for' or $data = 'case' or $data = 'esac' or $data = 'in' or $data = '-n' or $data = '[' or $data = ']' or - $data = '-z' or $data = '-f' or $data = '<<-' or $data = '>' or $data = 'EOF'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- Default keywords --> - <xsl:when test="$data = 'use' or $data = 'has_version' or $data = 'best_version' or $data = 'use_with' or $data = 'use_enable' or - $data = 'check_KV' or $data = 'keepdir' or $data = 'econf' or $data = 'die' or $data = 'einstall' or $data = 'einfo' or - $data = 'elog' or - $data = 'ewarn' or $data = 'eerror' or $data = 'diropts' or $data = 'dobin' or $data = 'docinto' or $data = 'dodoc' or - $data = 'doexe' or $data = 'dohard' or $data = 'dohtml' or $data = 'doinfo' or $data = 'doins' or $data = 'dolib' or - $data = 'dolib$dataa' or $data = 'dolib$dataso' or $data = 'doman' or $data = 'dosbin' or $data = 'dosym' or $data = 'emake' or - $data = 'exeinto' or $data = 'exeopts' or $data = 'fowners' or $data = 'fperms' or $data = 'insinto' or $data = 'insopts' or - $data = 'into' or $data = 'libopts' or $data = 'newbin' or $data = 'newexe' or $data = 'newins' or $data = 'newman' or - $data = 'newsbin' or $data = 'prepall' or $data = 'prepalldocs' or $data = 'prepallinfo' or $data = 'prepallman' or - $data = 'prepallstrip' or $data = 'has' or $data = 'unpack' or $data = 'dosed' or $data = 'into' or - $data = 'doinitd' or $data = 'doconfd' or $data = 'doenvd' or $data = 'dojar' or $data = 'domo' or $data = 'dodir' or - $data = 'ebegin' or $data = 'eend' or $data = 'newconfd' or $data = 'newdoc' or $data = 'newenvd' or $data = 'newinitd' or - $data = 'newlib.a' or $data = 'newlib.so' or $data = 'hasq' or $data = 'hasv' or $data = 'useq' or $data = 'usev'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- Sandbox --> - <xsl:when test="$data = 'addread' or $data = 'addwrite' or $data = 'adddeny' or $data = 'addpredict'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- Recognised functions --> - <xsl:when test="$data = 'pkg_nofetch' or $data = 'pkg_setup' or $data = 'src_unpack' or $data = 'src_compile' or $data = 'src_test' or - $data = 'src_install' or $data = 'pkg_preinst' or $data = 'pkg_postinst' or $data = 'pkg_prerm' or $data = 'pkg_postrm' or - $data = 'pkg_config'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- Inherit --> - <xsl:when test="$data = 'inherit'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- eutils --> - <xsl:when test="$data = 'gen_usr_ldscript' or $data = 'draw_line' or $data = 'epatch' or $data = 'have_NPTL' or $data = 'get_number_of_jobs' or - $data = 'egetent' or $data = 'emktemp' or $data = 'enewuser' or $data = 'enewgroup' or $data = 'edos2unix' or - $data = 'make_desktop_entry' or $data = 'unpack_pdv' or $data = 'unpack_makeself' or $data = 'check_license' or - $data = 'cdrom_get_cds' or $data = 'cdrom_load_next' or $data = 'cdrom_locate_file_on_cd' or $data = 'strip-linguas' or - $data = 'epause' or $data = 'ebeep' or $data = 'built_with_use' or $data = 'make_session_desktop' or $data = 'domenu' or - $data = 'doicon' or $data = 'find_unpackable_file' or $data = 'unpack_pdv' or $data = 'set_arch_to_kernel' or - $data = 'set_arch_to_portage' or $data = 'preserve_old_lib' or $data = 'preserve_old_lib_notify' or $data = 'built_with_use' or - $data = 'epunt_cxx' or $data = 'dopamd' or $data = 'newpamd' or $data = 'make_wrapper'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- flag-o-matic --> - <xsl:when test="$data = 'setup-allowed-flags' or $data = 'filter-flags' or $data = 'filter-lfs-flags' or $data = 'append-lfs-flags' or - $data = 'append-flags' or $data = 'replace-flags' or $data = 'replace-cpu-flags' or $data = 'is-flag' or $data = 'filter-mfpmath' or - $data = 'strip-flags' or $data = 'test_flag' or $data = 'test_version_info' or $data = 'strip-unsupported-flags' or - $data = 'get-flag' or $data = 'has_hardened' or $data = 'has_pic' or $data = 'has_pie' or $data = 'has_ssp_all' or $data = 'has_ssp' or - $data = 'has_m64' or $data = 'has_m32' or $data = 'replace-sparc64-flags' or $data = 'append-ldflags' or $data = 'filter-ldflags' or - $data = 'fstack-flags' or $data = 'gcc2-flags'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- gcc --> - <xsl:when test="$data = 'gcc-getCC' or $data = 'gcc-getCXX' or $data = 'gcc-fullversion' or $data = 'gcc-version' or - $data = 'gcc-major-version' or $data = 'gcc-minor-version' or $data = 'gcc-micro-version' or - $data = 'gcc-libpath' or $data = 'gcc-libstdcxx-version' or $data = 'gcc-libstdcxx-major-version' or - $data = 'gcc2-flags'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- libtool --> - <xsl:when test="$data = 'elibtoolize' or $data = 'uclibctoolize' or $data = 'darwintoolize'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- fixheadtails --> - <xsl:when test="$data = 'ht_fix_file' or $data = 'ht_fix_all'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- fdo-mime --> - <xsl:when test="$data = 'fdo-mime_desktop_database_update' or $data = 'fdo-mime_mime_database_update'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- webapp --> - <xsl:when test="$data = 'webapp_checkfileexists' or $data = 'webapp_import_config' or $data = 'webapp_strip_appdir' or - $data = 'webapp_strip_d' or $data = 'webapp_strip_cwd' or $data = 'webapp_configfile' or $data = 'webapp_hook_script' or - $data = 'webapp_postinst_txt' or $data = 'webapp_postupgrade_txt' or $data = 'webapp_runbycgibin' or - $data = 'webapp_serverowned' or $data = 'webapp_server_configfile' or $data = 'webapp_sqlscript' or - $data = 'webapp_src_install' or $data = 'webapp_pkg_postinst' or $data = 'webapp_pkg_setup' or - $data = 'webapp_getinstalltype' or $data = 'webapp_src_preinst' or $data = 'webapp_pkg_prerm'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- versionator --> - <xsl:when test="$data = 'get_all_version_components' or $data = 'version_is_at_least' or $data = 'get_version_components' or - $data = 'get_major_version' or $data = 'get_version_component_range' or $data = 'get_after_major_version' or - $data = 'replace_version_separator' or $data = 'replace_all_version_separators' or $data = 'delete_version_separator' or - $data = 'delete_all_version_separators'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- cvs --> - <xsl:when test="$data = 'cvs_fetch' or $data = 'cvs_src_unpack'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- bash-completion --> - <xsl:when test="$data = 'dobashcompletion' or $data = 'bash-completion_pkg_postinst' or $data = 'complete'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- vim-plugin --> - <xsl:when test="$data = 'vim-plugin_src_install' or $data = 'vim-plugin_pkg_postinst' or $data = 'vim-plugin_pkg_postrm' or - $data = 'update_vim_afterscripts' or $data = 'display_vim_plugin_help'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- vim-doc --> - <xsl:when test="update_vim_helptags"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- multilib --> - <xsl:when test="$data = 'has_multilib_profile' or $data = 'get_libdir' or $data = 'get_multilibdir' or $data = 'get_libdir_override' or - $data = 'get_abi_var' or $data = 'get_abi_CFLAGS' or $data = 'get_abi_LDFLAGS' or - $data = 'get_abi_CHOST' or $data = 'get_abi_FAKE_TARGETS' or $data = 'get_abi_CDEFINE' or - $data = 'get_abi_LIBDIR' or $data = 'get_install_abis ' or $data = 'get_all_abis' or $data = 'get_all_libdirs' or - $data = 'is_final_abi' or $data = 'number_abis' or $data = 'get_ml_incdir' or $data = 'prep_ml_includes' or - $data = 'create_ml_includes' or $data = 'create_ml_includes-absolute' or $data = 'create_ml_includes-tidy_path' or - $data = 'create_ml_includes-listdirs' or $data = 'create_ml_includes-makedestdirs' or $data = 'create_ml_includes-allfiles' or - $data = 'create_ml_includes-sym_for_dir'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- toolchain-funcs --> - <xsl:when test="$data = 'tc-getPROG' or $data = 'tc-getAR' or $data = 'tc-getAS' or $data = 'tc-getCC' or $data = 'tc-getCXX' or $data = 'tc-getLD' or $data = 'tc-getNM' or - $data = 'tc-getRANLIB' or $data = 'tc-getF77' or $data = 'tc-getGCJ' or $data = 'tc-getBUILD_CC' or - $data = 'tc-export' or $data = 'ninj' or $data = 'tc-is-cross-compiler' or $data = 'tc-ninja_magic_to_arch' or - $data = 'tc-arch-kernel' or $data = 'tc-arch' or $data = 'tc-endian' or $data = 'gcc-fullversion' or - $data = 'gcc-version' or $data = 'gcc-major-version' or $data = 'gcc-minor-version' or $data = 'gcc-micro-version'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- cron --> - <xsl:when test="$data = 'docrondir' or $data = 'docron' or $data = 'docrontab' or $data = 'cron_pkg_postinst'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- games --> - <xsl:when test="$data = 'egamesconf' or $data = 'egamesinstall' or $data = 'gameswrapper' or $data = 'dogamesbin' or $data = 'dogamessbin' or $data = 'dogameslib' or - $data = 'dogameslib$dataa' or $data = 'dogameslib$dataso' or $data = 'newgamesbin' or $data = 'newgamessbin' or - $data = 'gamesowners' or $data = 'gamesperms' or $data = 'prepgamesdirs' or $data = 'gamesenv' or $data = 'games_pkg_setup' or - $data = 'games_src_compile' or $data = 'games_pkg_postinst' or $data = 'games_ut_unpack' or $data = 'games_umod_unpack' or - $data = 'games_make_wrapper'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- subversion --> - <xsl:when test="$data = 'subversion_svn_fetch' or $data = 'subversion_bootstrap' or $data = 'subversion_src_unpack'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- alternatives --> - <xsl:when test="$data = 'alternatives_auto_makesym' or $data = 'alternatives_makesym' or $data = 'alternatives_pkg_postinst' or - $data = 'alternatives_pkg_postrm'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- rpm --> - <xsl:when test="$data = 'rpm_unpack' or $data = 'rpm_src_unpack'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- python --> - <xsl:when test="$data = 'python_version' or $data = 'python_tkinter_exists' or $data = 'python_mod_exists' or $data = 'python_mod_compile' or - $data = 'python_mod_optimize' or $data = 'python_mod_cleanup' or $data = 'python_makesym' or $data = 'python_disable_pyc' or - $data = 'python_enable_pyc'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- check-kernel --> - <xsl:when test="$data = 'check_version_h' or $data = 'get_KV_info' or $data = 'is_2_4_kernel' or $data = 'is_2_5_kernel' or $data = 'is_2_6_kernel' or - $data = 'kernel_supports_modules'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- perl-module --> - <xsl:when test="$data = 'perl-module_src_prep' or $data = 'perl-module_src_compile' or $data = 'perl-module_src_test' or - $data = 'perl-module_src_install' or $data = 'perl-module_pkg_setup' or $data = 'perl-module_pkg_preinst' or - $data = 'perl-module_pkg_postinst' or $data = 'perl-module_pkg_prerm' or $data = 'perl-module_pkg_postrm' or - $data = 'perlinfo' or $data = 'fixlocalpod' or $data = 'updatepod'"> - <span class="Statement"><xsl:value-of select="$data"/></span> + <xsl:when test="str:tokenize($shell-keywords)[$data = .]"> + <span class="Statement"><xsl:value-of select="$data"/></span> </xsl:when> - <!-- depend$dataapache --> - <xsl:when test="$data = 'need_apache' or $data = 'need_apache1' or $data = 'need_apache2'"> - <span class="Statement"><xsl:value-of select="$data"/></span> + <!-- Package manager commands --> + <xsl:when test="str:tokenize($pkg-mgr-keywords)[$data = .]"> + <span class="Statement"><xsl:value-of select="$data"/></span> </xsl:when> - <!-- apache-module --> - <xsl:when test="$data = 'apache-module_pkg_setup' or $data = 'apache-module_src_compile' or - $data = 'apache-module_src_install' or $data = 'apache-module_pkg_postinst' or $data = 'acache_cd_dir' or - $data = 'apache_mod_file' or $data = 'apache_doc_magic' or $data = 'apache1_src_compile' or $data = 'apache1_src_install' or - $data = 'apache1_pkg_postinst' or $data = 'apache2_pkg_setup' or $data = 'apache2_src_compile' or - $data = 'apache1_src_install' or $data = 'apache2_pkg_postinst'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- pam --> - <xsl:when test="$data = 'dopamd' or $data = 'newpamd' or $data = 'dopamsecurity' or $data = 'newpamsecurity' or $data = 'getpam_mod_dir' or - $data = 'dopammod' or $data = 'newpammod' or $data = 'pamd_mimic_system'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- virtualx --> - <xsl:when test="$data = 'virtualmake' or $data = 'Xmake' or $data = 'Xemake' or $data = 'Xeconf'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- gnome2 --> - <xsl:when test="$data = 'gnome2_src_configure' or $data = 'gnome2_src_compile' or $data = 'gnome2_src_install' or - $data = 'gnome2_gconf_install' or $data = 'gnome2_gconf_uninstal' or $data = 'gnome2_omf_fix' or - $data = 'gnome2_scrollkeeper_update' or $data = 'gnome2_pkg_postinst' or $data = 'gnome2_pkg_postrm'"> - <span class="Statement"><xsl:value-of select="$data"/></span> + <!-- Eclass commands --> + <xsl:when test="str:tokenize($eclass-keywords)[$data = .]"> + <span class="Statement"><xsl:value-of select="$data"/></span> </xsl:when> <!-- No match return --> @@ -347,25 +221,27 @@ <!-- Scan for comments. If a comment is found then this is a positional index that is non-zero that refers to the last node that is not a comment. --> - <xsl:variable name="commentSeeker" select="count(str:tokenize_plasmaroo(substring-before($data, concat(' ', $lang.highlight.ebuild.commentChar))))"/> + <xsl:variable name="commentSeeker" select="count(str:tokenize_plasmaroo(substring-before($data, + concat(' ', $lang.highlight.ebuild.commentChar))))"/> <!-- Scan for quotes... --> <xsl:for-each select="exslt:node-set($tokenizedData)"> <xsl:variable name="myPos" select="position()"/> <xsl:variable name="quotePos" select="count(../*[@delimiter='"' and position() < $myPos])"/> - + <xsl:choose> <!-- See if we should be processing comments by now; we need to test for - two possible cases: * commentSeeker != 0 (so we have a comment), or, - * the first token is a "#" --> - <xsl:when test="($commentSeeker != 0 and position() > $commentSeeker) or substring(../*[position()=1], 1, 1) = $lang.highlight.ebuild.commentChar or + two possible cases: * commentSeeker != 0 (so we have a comment), or, + * the first token is a "#" --> + <xsl:when test="($commentSeeker != 0 and position() > $commentSeeker) or + substring(../*[position()=1], 1, 1) = $lang.highlight.ebuild.commentChar or . = $lang.highlight.ebuild.commentChar"> <span class="Comment"><xsl:value-of select="."/></span> </xsl:when> <!-- Highlight a quote --> <xsl:when test=". = '"'"> - <span class="Statement">"</span> + <span class="Statement">"</span> </xsl:when> <!-- If we're inside quotes stop here --> @@ -377,14 +253,14 @@ </xsl:when> <!-- Highlight functions; - @token_regexp = [^\w]+() - @pos = 1 --> + @token_regexp = [^\w]+() + @pos = 1 --> <xsl:when test="position() = 1 and substring(., string-length(.)-1) = '()'"> <span class="Special"><xsl:value-of select="."/></span> </xsl:when> <!-- Highlight variable assignments; - @regexp = [\w]=["']{...}['"] --> + @regexp = [\w]=["']{...}['"] --> <xsl:when test="contains(., '=')"> <span class="Identifier"><xsl:value-of select="substring-before(., '=')"/></span> <span class="Constant">=</span> @@ -394,21 +270,26 @@ </xsl:when> <xsl:when test=". = '{' or . = '}' or . = '\' or . = '('"> - <span class="PreProc"><xsl:value-of select="."/></span> + <span class="PreProc"><xsl:value-of select="."/></span> </xsl:when> <xsl:when test=". = '||' or . = '&&' or . = '|'"> - <span class="Statement"><xsl:value-of select="."/></span> + <span class="Statement"><xsl:value-of select="."/></span> </xsl:when> <!-- No match return --> <xsl:otherwise> <xsl:call-template name="lang.highlight.ebuild.subtokenate"> - <xsl:with-param name="data" select="."/> - </xsl:call-template> + <xsl:with-param name="data" select="."/> + </xsl:call-template> </xsl:otherwise> </xsl:choose> </xsl:for-each> </xsl:template> </xsl:stylesheet> + +<!-- Local Variables: --> +<!-- indent-tabs-mode: nil --> +<!-- fill-column: 120 --> +<!-- End: --> diff --git a/xsl/lang.highlight.m4.xsl b/xsl/lang.highlight.m4.xsl index d15718b..9d75967 100644 --- a/xsl/lang.highlight.m4.xsl +++ b/xsl/lang.highlight.m4.xsl @@ -1,3 +1,4 @@ +<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform' xmlns:str="http://exslt.org/strings" xmlns:exslt="http://exslt.org/common" @@ -40,14 +41,14 @@ <xsl:call-template name="lang.highlight.m4.subtokenate"> <xsl:with-param name="data" select="substring-after($data, '[')"/> <xsl:with-param name="nokeywords" select="$nokeywords"/> - </xsl:call-template> + </xsl:call-template> </xsl:when> <xsl:when test="substring($data, string-length($data)) = ')'"> <xsl:call-template name="lang.highlight.m4.subtokenate"> <xsl:with-param name="data" select="substring($data, 1, string-length($data)-1)"/> <xsl:with-param name="nokeywords" select="$nokeywords"/> - </xsl:call-template> + </xsl:call-template> <span class="Special">)</span> </xsl:when> @@ -55,7 +56,7 @@ <xsl:call-template name="lang.highlight.m4.subtokenate"> <xsl:with-param name="data" select="substring($data, 1, string-length($data)-2)"/> <xsl:with-param name="nokeywords" select="$nokeywords"/> - </xsl:call-template> + </xsl:call-template> <span class="Special">],</span> </xsl:when> @@ -63,7 +64,7 @@ <xsl:call-template name="lang.highlight.m4.subtokenate"> <xsl:with-param name="data" select="substring($data, 1, string-length($data)-1)"/> <xsl:with-param name="nokeywords" select="$nokeywords"/> - </xsl:call-template> + </xsl:call-template> <span class="Special">,</span> </xsl:when> @@ -81,7 +82,7 @@ $data = 'while' or $data = 'do' or $data = 'read' or $data = 'done' or $data = 'make' or $data = 'echo' or $data = 'cd' or $data = 'local' or $data = 'return' or $data = 'for' or $data = 'case' or $data = 'esac' or $data = 'in' or $data = '-n' or $data = '[' or $data = ']' or $data = '-z' or $data = '-f' or $data = '<<-' or $data = '>' or $data = 'EOF' or $data = 'test'"> - <span class="Statement"><xsl:value-of select="$data"/></span> + <span class="Statement"><xsl:value-of select="$data"/></span> </xsl:when> <!-- No match return --> @@ -101,7 +102,7 @@ <xsl:for-each select="exslt:node-set($tokenizedData)"> <xsl:variable name="myPos" select="position()"/> <xsl:variable name="quotePos" select="count(../*[@delimiter='"' and position() < $myPos])"/> - + <xsl:choose> <xsl:when test="../*[position()=1] = 'dnl'"> <span class="Comment"><xsl:value-of select="."/></span> @@ -109,7 +110,7 @@ <!-- Highlight a quote --> <xsl:when test=". = '"'"> - <span class="Statement">"</span> + <span class="Statement">"</span> </xsl:when> <!-- If we're inside quotes stop here --> @@ -123,7 +124,7 @@ </xsl:when> <!-- Highlight variable assignments; - @regexp = [\w]=["']{...}['"] --> + @regexp = [\w]=["']{...}['"] --> <xsl:when test="contains(., '=')"> <xsl:call-template name="lang.highlight.m4.subtokenate"> <xsl:with-param name="data" select="substring-before(., '=')"/> @@ -137,11 +138,16 @@ <!-- No match return --> <xsl:otherwise> <xsl:call-template name="lang.highlight.m4.subtokenate"> - <xsl:with-param name="data" select="."/> - </xsl:call-template> + <xsl:with-param name="data" select="."/> + </xsl:call-template> </xsl:otherwise> </xsl:choose> </xsl:for-each> </xsl:template> </xsl:stylesheet> + +<!-- Local Variables: --> +<!-- indent-tabs-mode: nil --> +<!-- fill-column: 120 --> +<!-- End: --> diff --git a/xsl/lang.highlight.make.xsl b/xsl/lang.highlight.make.xsl index dd36026..dbc082a 100644 --- a/xsl/lang.highlight.make.xsl +++ b/xsl/lang.highlight.make.xsl @@ -1,3 +1,4 @@ +<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform' xmlns:str="http://exslt.org/strings" xmlns:exslt="http://exslt.org/common" @@ -39,7 +40,7 @@ <!-- sh grammar --> <xsl:when test="$data = '$?' or $data = '>' or $data = '$@' or $data = ':'"> - <span class="Identifier"><xsl:value-of select="$data"/></span> + <span class="Identifier"><xsl:value-of select="$data"/></span> </xsl:when> <!-- No match return --> @@ -59,7 +60,7 @@ <xsl:for-each select="exslt:node-set($tokenizedData)"> <xsl:variable name="myPos" select="position()"/> <xsl:variable name="quotePos" select="count(../*[@delimiter='"' and position() < $myPos])"/> - + <xsl:choose> <xsl:when test="../*[position()=3] = '=' and $myPos = 1"> <span class="Type"><xsl:value-of select="."/></span> @@ -67,7 +68,7 @@ <!-- Highlight a quote --> <xsl:when test=". = '"'"> - <span class="Statement">"</span> + <span class="Statement">"</span> </xsl:when> <!-- If we're inside quotes stop here --> @@ -81,7 +82,7 @@ </xsl:when> <!-- Highlight variable assignments; - @regexp = [\w]=["']{...}['"] --> + @regexp = [\w]=["']{...}['"] --> <xsl:when test="contains(., '=')"> <xsl:call-template name="lang.highlight.make.subtokenate"> <xsl:with-param name="data" select="substring-before(., '=')"/> @@ -95,11 +96,16 @@ <!-- No match return --> <xsl:otherwise> <xsl:call-template name="lang.highlight.make.subtokenate"> - <xsl:with-param name="data" select="."/> - </xsl:call-template> + <xsl:with-param name="data" select="."/> + </xsl:call-template> </xsl:otherwise> </xsl:choose> </xsl:for-each> </xsl:template> </xsl:stylesheet> + +<!-- Local Variables: --> +<!-- indent-tabs-mode: nil --> +<!-- fill-column: 120 --> +<!-- End: --> diff --git a/xsl/lang.highlight.sgml.xsl b/xsl/lang.highlight.sgml.xsl index 4ae5e43..bdd06b7 100644 --- a/xsl/lang.highlight.sgml.xsl +++ b/xsl/lang.highlight.sgml.xsl @@ -1,3 +1,4 @@ +<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version='1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform' xmlns:str="http://exslt.org/strings" xmlns:exslt="http://exslt.org/common" @@ -31,11 +32,11 @@ <xsl:variable name="quotePos" select="count(../*[@delimiter='"' and position() < $myPos])"/> <xsl:variable name="tagPosOpen" select="count(../*[@delimiter='<' and position() < $myPos])"/> <xsl:variable name="tagPosClosed" select="count(../*[@delimiter='>' and position() < $myPos])"/> - + <xsl:choose> <!-- Highlight a quote --> <xsl:when test=". = '"'"> - <span class="Statement">"</span> + <span class="Statement">"</span> </xsl:when> <!-- If we're inside quotes stop here --> @@ -48,7 +49,7 @@ <xsl:when test="contains(., '=') and $tagPosOpen != $tagPosClosed"> <span class="Identifier"><xsl:value-of select="substring-before(., '=')"/></span> <span class="Constant">=</span> - <xsl:call-template name="lang.highlight.sgml.subtokenate"> + <xsl:call-template name="lang.highlight.sgml.subtokenate"> <xsl:with-param name="data" select="substring-after(., '=')"/> </xsl:call-template> </xsl:when> @@ -60,11 +61,16 @@ <!-- No match return --> <xsl:otherwise> <xsl:call-template name="lang.highlight.sgml.subtokenate"> - <xsl:with-param name="data" select="."/> - </xsl:call-template> + <xsl:with-param name="data" select="."/> + </xsl:call-template> </xsl:otherwise> </xsl:choose> </xsl:for-each> </xsl:template> </xsl:stylesheet> + +<!-- Local Variables: --> +<!-- indent-tabs-mode: nil --> +<!-- fill-column: 120 --> +<!-- End: --> diff --git a/xsl/str.tokenize.function.xsl b/xsl/str.tokenize.function.xsl index 2be90fe..3c3275d 100644 --- a/xsl/str.tokenize.function.xsl +++ b/xsl/str.tokenize.function.xsl @@ -1,88 +1,96 @@ -<?xml version="1.0"?>
-<!-- This is the EXSLT implementation of str:tokenize by Jeni Tennison,
- I've modified it to keep the tokens since we need them - plasmaroo -->
-
-<xsl:stylesheet version="1.0"
- xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
- xmlns:func="http://exslt.org/functions"
- xmlns:exsl="http://exslt.org/common"
- xmlns:str="http://exslt.org/strings"
- extension-element-prefixes="str func exsl xsl"
- exclude-result-prefixes="str func exsl xsl"
- xmlns="http://www.w3.org/1999/xhtml">
-
-<func:function name="str:tokenize_plasmaroo">
- <xsl:param name="string" select="''" />
- <xsl:param name="delimiters" select="' 	
'" />
- <xsl:choose>
- <xsl:when test="not($string)">
- <func:result select="/.." />
- </xsl:when>
- <xsl:when test="not(function-available('exsl:node-set'))">
- <xsl:message terminate="yes">
- ERROR: EXSLT - Functions implementation of str:tokenize relies on exsl:node-set().
- </xsl:message>
- </xsl:when>
- <xsl:otherwise>
- <xsl:variable name="tokens">
- <xsl:choose>
- <xsl:when test="not($delimiters)">
- <xsl:call-template name="str:_tokenize-characters">
- <xsl:with-param name="string" select="$string" />
- </xsl:call-template>
- </xsl:when>
- <xsl:otherwise>
- <xsl:call-template name="str:_tokenize-delimiters">
- <xsl:with-param name="string" select="$string" />
- <xsl:with-param name="delimiters" select="$delimiters" />
- </xsl:call-template>
- </xsl:otherwise>
- </xsl:choose>
- </xsl:variable>
- <func:result select="exsl:node-set($tokens)/*" />
- </xsl:otherwise>
- </xsl:choose>
-</func:function>
-
-<xsl:template name="str:_tokenize-characters">
- <xsl:param name="string" />
- <xsl:if test="$string">
- <token><xsl:value-of select="substring($string, 1, 1)" /></token>
- <xsl:call-template name="str:_tokenize-characters">
- <xsl:with-param name="string" select="substring($string, 2)" />
- </xsl:call-template>
- </xsl:if>
-</xsl:template>
-
-<xsl:template name="str:_tokenize-delimiters">
- <xsl:param name="string"/>
- <xsl:param name="delimiters"/>
- <xsl:variable name="delimiter" select="substring($delimiters, 1, 1)" />
- <xsl:choose>
- <xsl:when test="not($delimiter)">
- <token><xsl:value-of select="$string" /></token>
- </xsl:when>
- <xsl:when test="contains($string, $delimiter)">
- <xsl:if test="not(starts-with($string, $delimiter))">
- <xsl:call-template name="str:_tokenize-delimiters">
- <xsl:with-param name="string" select="substring-before($string, $delimiter)" />
- <xsl:with-param name="delimiters" select="substring($delimiters, 2)" />
- </xsl:call-template>
- <xsl:value-of select="$delimiter"/>
- </xsl:if>
- <delimiter><xsl:attribute name="delimiter"><xsl:value-of select="$delimiter"/></xsl:attribute><xsl:value-of select="$delimiter"/></delimiter>
- <xsl:call-template name="str:_tokenize-delimiters">
- <xsl:with-param name="string" select="substring-after($string, $delimiter)"/>
- <xsl:with-param name="delimiters" select="$delimiters"/>
- </xsl:call-template>
- </xsl:when>
- <xsl:otherwise>
- <xsl:call-template name="str:_tokenize-delimiters">
- <xsl:with-param name="string" select="$string" />
- <xsl:with-param name="delimiters" select="substring($delimiters, 2)" />
- </xsl:call-template>
- </xsl:otherwise>
- </xsl:choose>
-</xsl:template>
-
-</xsl:stylesheet>
+<?xml version="1.0" encoding="UTF-8"?> +<!-- This is the EXSLT implementation of str:tokenize by Jeni Tennison, + I've modified it to keep the tokens since we need them - plasmaroo --> + +<xsl:stylesheet version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:func="http://exslt.org/functions" + xmlns:exsl="http://exslt.org/common" + xmlns:str="http://exslt.org/strings" + extension-element-prefixes="str func exsl xsl" + exclude-result-prefixes="str func exsl xsl" + xmlns="http://www.w3.org/1999/xhtml"> + +<func:function name="str:tokenize_plasmaroo"> + <xsl:param name="string" select="''" /> + <xsl:param name="delimiters" select="' 	
'" /> + <xsl:choose> + <xsl:when test="not($string)"> + <func:result select="/.." /> + </xsl:when> + <xsl:when test="not(function-available('exsl:node-set'))"> + <xsl:message terminate="yes"> + ERROR: EXSLT - Functions implementation of str:tokenize relies on exsl:node-set(). + </xsl:message> + </xsl:when> + <xsl:otherwise> + <xsl:variable name="tokens"> + <xsl:choose> + <xsl:when test="not($delimiters)"> + <xsl:call-template name="str:_tokenize-characters"> + <xsl:with-param name="string" select="$string" /> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="str:_tokenize-delimiters"> + <xsl:with-param name="string" select="$string" /> + <xsl:with-param name="delimiters" select="$delimiters" /> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> + <func:result select="exsl:node-set($tokens)/*" /> + </xsl:otherwise> + </xsl:choose> +</func:function> + +<xsl:template name="str:_tokenize-characters"> + <xsl:param name="string" /> + <xsl:if test="$string"> + <token><xsl:value-of select="substring($string, 1, 1)" /></token> + <xsl:call-template name="str:_tokenize-characters"> + <xsl:with-param name="string" select="substring($string, 2)" /> + </xsl:call-template> + </xsl:if> +</xsl:template> + +<xsl:template name="str:_tokenize-delimiters"> + <xsl:param name="string"/> + <xsl:param name="delimiters"/> + <xsl:variable name="delimiter" select="substring($delimiters, 1, 1)" /> + <xsl:choose> + <xsl:when test="not($delimiter)"> + <token><xsl:value-of select="$string" /></token> + </xsl:when> + <xsl:when test="contains($string, $delimiter)"> + <xsl:if test="not(starts-with($string, $delimiter))"> + <xsl:call-template name="str:_tokenize-delimiters"> + <xsl:with-param name="string" select="substring-before($string, $delimiter)" /> + <xsl:with-param name="delimiters" select="substring($delimiters, 2)" /> + </xsl:call-template> + <xsl:value-of select="$delimiter"/> + </xsl:if> + <delimiter> + <xsl:attribute name="delimiter"><xsl:value-of select="$delimiter"/></xsl:attribute> + <xsl:value-of select="$delimiter"/> + </delimiter> + <xsl:call-template name="str:_tokenize-delimiters"> + <xsl:with-param name="string" select="substring-after($string, $delimiter)"/> + <xsl:with-param name="delimiters" select="$delimiters"/> + </xsl:call-template> + </xsl:when> + <xsl:otherwise> + <xsl:call-template name="str:_tokenize-delimiters"> + <xsl:with-param name="string" select="$string" /> + <xsl:with-param name="delimiters" select="substring($delimiters, 2)" /> + </xsl:call-template> + </xsl:otherwise> + </xsl:choose> +</xsl:template> + +</xsl:stylesheet> + +<!-- Local Variables: --> +<!-- indent-tabs-mode: nil --> +<!-- fill-column: 120 --> +<!-- End: --> |
