diff options
150 files changed, 6253 insertions, 3778 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 @@ -3,3 +3,7 @@ .depend documents.js eclass-reference/ + +# Emacs backup files and locks +*~ +.#* @@ -43,6 +43,9 @@ build: $(HTMLS) $(IMAGES) documents.js: bin/build_search_documents.py $(XMLS) @python3 bin/build_search_documents.py $(XMLS) > $@ && echo "$@ built" +%.svg : %.dot + dot -T svg -o $@ $< + %.png : %.svg rsvg-convert --output=$@ $< @@ -63,13 +66,15 @@ eclass-reference/text.xml: @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) depend.xsl devbook.xsl - @xsltproc depend.xsl $(XMLS) | sed ':x;s%[^ /]*/\.\./%%;tx' > $@ +.depend: $(XMLS) eclass-reference/text.xml depend.xsl devbook.xsl + @xsltproc depend.xsl $(XMLS) > $@ install: all set -e; \ @@ -82,11 +87,15 @@ install: all install -m 644 $(JS_FILES) "$(DESTDIR)$(htmldir)"/; \ fi -validate: - @xmllint --noout --dtdvalid devbook.dtd $(XMLS) \ - && echo "xmllint validation successful" +validate: devbook.rng + @xmllint --noout --quiet --relaxng $< $(XMLS) + @echo "xmllint validation successful" -# Run app-text/tidy-html5 on the output to detect mistakes. +%.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) @@ -96,8 +105,10 @@ tidy: $(HTMLS) $(ECLASS_HTMLS) | tidy -q -errors --drop-empty-elements no 2>&1) \ || { status=$$?; echo "Failed on $${f}:"; echo "$${output}"; }; \ done; \ - test $${status} -eq 0 && echo "tidy validation successful"; \ exit $${status} + @echo "tidy validation successful" + +check: validate tidy dist: COMMITDATE=$$(TZ=UTC git log -1 --pretty="format:%cd" \ @@ -109,6 +120,6 @@ dist: clean: @rm -f $(HTMLS) $(IMAGES) documents.js .depend -.PHONY: all prereq build install validate tidy dist clean +.PHONY: all prereq build install check validate tidy dist clean -include .depend diff --git a/appendices/common-problems/text.xml b/appendices/common-problems/text.xml index b4fd3ea..6ebc098 100644 --- a/appendices/common-problems/text.xml +++ b/appendices/common-problems/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/common-problems/"> <chapter> -<title>Common Problems</title> +<title>Common problems</title> <body> <p> @@ -11,13 +11,13 @@ and QA notices. </body> <section> -<title>Handling QA Notices</title> +<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> @@ -28,7 +28,7 @@ covered here. </body> <subsection> -<title>QA Notice: USE Flag foo not in IUSE</title> +<title>QA notice: USE flag foo not in IUSE</title> <body> <p> @@ -42,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> @@ -57,11 +57,10 @@ in use, there are various alternatives: </dt> <dd> 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>eapi7-ver</c> eclass is often of use here. - See <uri link="::ebuild-writing/variables/#Version and Name Formatting Issues"/>, - <c>man eapi7-ver.eclass</c> and <uri - link="::tools-reference/bash/#Bash Variable Manipulation"/>. + 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> @@ -87,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> @@ -101,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> @@ -111,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> @@ -127,15 +126,15 @@ 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> When working with eclasses in an overlay with a stale cache. See <uri - link="::general-concepts/overlay/#Overlay and Eclasses"/>. + 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> @@ -146,34 +145,12 @@ you see this notice locally. If you see this notice when working with a pure <c>emerge sync</c> over <c>rsync</c> setup, it is probably a genuine issue. </p> -<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> </subsection> </section> <section> -<title>Handling <c>repoman</c> Messages</title> -<body> - -<todo> -write me -</todo> - -</body> -</section> - -<section> -<title>Handling Access Violations</title> +<title>Handling access violations</title> <body> <p> diff --git a/appendices/contributing/text.xml b/appendices/contributing/text.xml index 10ab565..2704463 100644 --- a/appendices/contributing/text.xml +++ b/appendices/contributing/text.xml @@ -1,13 +1,17 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/contributing/"> <chapter> -<title>Contributing to This Document</title> +<title>Contributing to this document</title> <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> @@ -66,7 +70,7 @@ top-level directory, which will validate all XML files using <c>xmllint</c>. </section> <section> -<title>Quick Introduction to DevBook XML</title> +<title>Quick introduction to DevBook XML</title> <body> <p> @@ -94,7 +98,7 @@ amount of depth. definition lists. Do <e>not</e> indent text in ordinary paragraph blocks. </dd> <dt> - Code Samples + Code samples </dt> <dd> You can use the normal GuideXML tag <c><pre></c> when you need @@ -120,7 +124,7 @@ amount of depth. </section> <section> -<title>Style Guidelines</title> +<title>Style guidelines</title> <body> <ul> diff --git a/appendices/contributors/text.xml b/appendices/contributors/text.xml index e80dbcb..5ac92b7 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> @@ -10,55 +10,55 @@ This page lists the contributions to the Gentoo Development Guide: <authors> <author name="Ciaran McCreesh" email="ciaran.mccreesh@blueyonder.co.uk"> - Main Content + 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="::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="::general-concepts/use-flags/#Conflicting USE Flags"/> + <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="::general-concepts/autotools/#aclocal and m4 Files"/> + <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="Ursula Maplehurst" email="plasm@roo.me.uk"> - Previous maintainer (XSL Stylesheets, legacy Developer Handbook content) + Previous maintainer (XSL stylesheets, legacy Developer Handbook content) </author> <author name="Mark Loeser" email="halcy0n@gentoo.org"> - XSL Stylesheets, previous 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"> @@ -68,10 +68,10 @@ Misc <uri link="::ebuild-maintenance/"/>, <uri link="::appendices/editor-configuration/emacs/"/>, <uri link="::appendices/devbook-guide/"/>, - DTD, XSL stylesheet, eclass conversion + DTD, XSL stylesheets, 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 @@ -109,21 +109,25 @@ Misc </author> <author name="MichaÅ‚ Górny" email="mgorny@gentoo.org"> <uri link="::general-concepts/"/>, - <uri link="::ebuild-writing/users-and-groups/"/>, - <uri link="::ebuild-writing/variables/"/>, - <uri link="::ebuild-writing/functions/src_test/"/>, + <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/"/> + <uri link="::ebuild-writing/functions/src_prepare/eapply/"/> </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"/> + <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> diff --git a/appendices/devbook-guide/text.xml b/appendices/devbook-guide/text.xml index d37bbce..c725307 100644 --- a/appendices/devbook-guide/text.xml +++ b/appendices/devbook-guide/text.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/devbook-guide/"> <chapter> -<title>Gentoo DevBook XML Guide</title> +<title>Gentoo DevBook XML guide</title> <section> <title>DevBook XML design goals</title> @@ -11,7 +11,7 @@ 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 guide into other formats, such as DocBook +This makes it easy to transform DevBook XML into other formats, such as DocBook XML/SGML or web-ready HTML. </p> @@ -24,8 +24,6 @@ documents. </section> <section> -<title>Devbook XML</title> -<subsection> <title>Basic structure</title> <body> @@ -38,7 +36,7 @@ used in a DevBook XML document: <?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/devbook-guide/"> <chapter> -<title>Gentoo DevBook XML Guide</title> +<title>Gentoo DevBook XML guide</title> </codesample> <p> @@ -56,11 +54,6 @@ one chapter. Its <c><title></c> is used to set the title for the entire document. </p> -<important> -The <c><title></c> element cannot contain any newlines. Make sure it is -in one line, including its opening and closing tags. -</important> - <p> All tags must be closed of course, so the document ends with: </p> @@ -71,7 +64,7 @@ All tags must be closed of course, so the document ends with: </codesample> </body> -</subsection> + <subsection> <title>Sections and subsections</title> <body> @@ -185,6 +178,11 @@ This is 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> @@ -219,25 +217,33 @@ This is important. 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> -<subsection> -<title>The <body> tags</title> +</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> and <c><warning></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: +<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> --> @@ -248,40 +254,7 @@ preserve their whitespace exactly, making them well-suited for code excerpts: </codesample> </body> -</subsection> -<subsection> -<title><c>, <b>, and <e></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> -</body> -</subsection> <subsection> <title>Code samples and colour-coding</title> <body> @@ -345,7 +318,7 @@ RDEPEND="sys-libs/ncurses:0= DEPEND="${RDEPEND}" BDEPEND="virtual/pkgconfig" -src_install() { +src_install() { dobin mg doman mg.1 dodoc README tutorial @@ -355,30 +328,6 @@ src_install() { </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>Figures</title> <body> @@ -421,32 +370,32 @@ 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> +<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> @@ -511,6 +460,72 @@ together: </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> @@ -518,12 +533,12 @@ together: <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 +<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>. +<uri link="::quickstart/#First ebuild">First ebuild</uri>, type +<c><uri link="::quickstart/#First ebuild">First ebuild</uri></c>. </p> <p> @@ -531,9 +546,9 @@ 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 +<c><uri link="::quickstart/#First ebuild"/></c> render as <uri link="::ebuild-writing/file-format/"/> and -<uri link="::quickstart/#First Ebuild"/>, respectively. +<uri link="::quickstart/#First ebuild"/>, respectively. </p> </body> @@ -541,7 +556,7 @@ I could have written the two examples above in more compact form: </section> <section> -<title>Coding Style</title> +<title>Coding style</title> <body> <p> @@ -559,12 +574,12 @@ Both sections are described next. </body> <subsection> -<title>Internal Coding Style</title> +<title>Internal coding style</title> <body> <p> <b>Newlines</b> must be placed immediately after <e>every</e> DevBook XML tag -(both opening as closing), except for: +(both opening and closing), except for: <c><title></c>, <c><th></c>, <c><ti></c>, <c><li></c>, <c><dt></c>, <c><dd></c>, @@ -579,6 +594,8 @@ Both sections are described next. <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> @@ -597,7 +614,7 @@ 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. +DevBook XML documents (again, except for <pre> and <codesample>). </p> <p> @@ -657,7 +674,7 @@ fixed-width font. </body> </subsection> <subsection> -<title>External Coding Style</title> +<title>External coding style</title> <body> <p> @@ -680,6 +697,12 @@ with a capital letter. </codesample> <p> +Titles should use sentence case, i.e. their first word should start with a +capital letter, and all other words (except proper nouns) should be in lower +case. +</p> + +<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 diff --git a/appendices/editor-configuration/emacs/text.xml b/appendices/editor-configuration/emacs/text.xml index f822388..df3b94b 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> @@ -50,9 +50,7 @@ automatically before saving the file. <p> Other useful settings can be disabled backup files (by <c>(setq make-backup-files nil)</c>), so you don't clutter the git -repository -directories and confuse repoman with it (by adding unnecessary entries -into a Manifest file e.g.). Emacs can even contact the outside world +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> @@ -82,7 +80,7 @@ for each document type. </section> <section> -<title>Further Reading</title> +<title>Further reading</title> <body> <ul> diff --git a/appendices/editor-configuration/text.xml b/appendices/editor-configuration/text.xml index 5bb9390..7b50b48 100644 --- a/appendices/editor-configuration/text.xml +++ b/appendices/editor-configuration/text.xml @@ -1,11 +1,11 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/editor-configuration/"> <chapter> -<title>Editor Configuration</title> +<title>Editor configuration</title> <body> <p> -This section provides hints as to how to configue your text editor for working +This section provides hints as to how to configure your text editor for working with ebuilds. </p> 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 15edb22..95eb812 100644 --- a/appendices/further-reading/text.xml +++ b/appendices/further-reading/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/further-reading/"> <chapter> -<title>Further Reading</title> +<title>Further reading</title> <body> <p> diff --git a/appendices/text.xml b/appendices/text.xml index f5439b7..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> diff --git a/appendices/todo-list/text.xml b/appendices/todo-list/text.xml index e8175c5..c6db2a8 100644 --- a/appendices/todo-list/text.xml +++ b/appendices/todo-list/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="appendices/todo-list/"> <chapter> -<title>TODO List</title> +<title>TODO list</title> <body> <p> This TODO list is automatically generated from the <c><todo></c> directives in other documents. diff --git a/archs/alpha/text.xml b/archs/alpha/text.xml index 9087c09..9d0500e 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> @@ -12,7 +12,7 @@ The Alpha port uses the <c>alpha</c> keyword. It focuses upon HP (formerly Compa </body> <section> -<title>Alpha Kernel and Userland ABIs</title> +<title>Alpha kernel and userland ABIs</title> <body> <p> @@ -28,7 +28,7 @@ little endian. </section> <section> -<title>Additional Alpha Keywording Requirements</title> +<title>Additional Alpha keywording requirements</title> <body> <p> @@ -42,7 +42,7 @@ like to know about it. </section> <section> -<title>Alpha Instruction Set and Performance Notes</title> +<title>Alpha instruction set and performance notes</title> <body> <p> @@ -87,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> @@ -108,7 +108,7 @@ this results in errors during the compilation aborting emerge. </section> <section> -<title>Contacting the Alpha Team</title> +<title>Contacting the Alpha team</title> <body> <p> @@ -126,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> @@ -134,7 +134,7 @@ The Alpha team can be contacted: </section> <section> -<title>Other Resources</title> +<title>Other resources</title> <body> <ul> diff --git a/archs/amd64/text.xml b/archs/amd64/text.xml index e4713f5..05cce5f 100644 --- a/archs/amd64/text.xml +++ b/archs/amd64/text.xml @@ -1,10 +1,10 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="archs/amd64/"> <chapter> -<title>Arch Specific Notes — AMD64/EM64T</title> +<title>Arch specific notes — AMD64/EM64T</title> <section> -<title>Position Independent Code Issues</title> +<title>Position Independent Code issues</title> <body> <p> @@ -69,8 +69,9 @@ 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> @@ -82,32 +83,33 @@ done. It should only be applied to shared objects. <body> <p> -The current AMD64 processors are able to natively run 32bit code on a 64bit +The current AMD64 processors are able to natively run 32-bit code on a 64-bit kernel. Therefore, you can run programs compiled for x86 in an amd64 environment. -However, 32bit applications need to be linked against 32bit libraries. Mixing -them won't work. For this reason the libraries are sorted, 32bit libraries normally -go to <c>/lib32</c> respectively <c>/usr/lib32</c>, the 64bit ones normally to <c>/lib64</c> or -<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. +However, 32-bit applications need to be linked against 32-bit libraries. Mixing +them won't work. For this reason the libraries are sorted, 32-bit libraries +normally go to <c>/lib32</c> respectively <c>/usr/lib32</c>, the 64-bit ones +normally to <c>/lib64</c> or <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> +<title>Multilib toolchain</title> <subsubsection> <title>GCC</title> <body> <p> -To generate 32bit code, we need a multilib-capable GCC. On other architectures, +To generate 32-bit code, we need a multilib-capable GCC. On other architectures, this functionality is enabled with the USE flag <c>multilib</c>. This is also true for amd64 with the <e>pre</e>-2005.0 profiles. From 2005.0 on, you have to choose whether you want multilib support or not by selecting the profile. Choose <c>2005.0/no-multilib</c> if you don't want it, all other profiles have the <c>multilib</c> USE flag masked, you're forced to it. With these profiles, GCC will produce x86-code whenever you add <c>-m32</c> to its command line. Adding <c>-m64</c> -or omitting any bit-width option will default to producing 64bit code. +or omitting any bit-width option will default to producing 64-bit code. </p> </body> @@ -118,10 +120,10 @@ or omitting any bit-width option will default to producing 64bit code. <body> <p> -If you've chosen a multilib profile, glibc will be built twice, once 64bit and -once 32bit. This is because nearly every application links against glibc. +If you've chosen a multilib profile, glibc will be built twice, once 64-bit and +once 32-bit. This is because nearly every application links against glibc. To understand how this is done in the ebuild, read -<uri link="::archs/amd64/#The ABI Variable"/>. +<uri link="::archs/amd64/#The ABI variable"/>. </p> </body> @@ -129,180 +131,93 @@ To understand how this is done in the ebuild, read </subsection> <subsection> -<title>The <c>emul-linux-x86-*</c> packages</title> +<title>32-bit 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="https://dev.gentoo.org/~pacho/emul.html">here.</uri> +As you read above, 32-bit applications must be linked against 32-bit libraries. +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> - Directory containing mixed-bit objects - </dd> - <dt> - dXX - </dt> - <dd> - Directory containing XXbit objects - </dd> - <dt> - l->foo - </dt> - <dd> - Link to foo - </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> </subsection> <subsection> -<title>The <c>multilib-strict</c> Feature</title> +<title>The <c>multilib-strict</c> feature</title> <body> <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 -called <b>multilib-strict</b>. It will prevent emerge from putting 64bit libraries +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 64-bit libraries into anything other than <c>(/usr)/lib64</c>. </p> @@ -318,25 +233,10 @@ this behaviour is controlled by the <c>MULTILIB_STRICT_EXEMPT</c> variable in <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 @@ -348,13 +248,13 @@ modifications! </subsection> <subsection> -<title>Headers and Multilib</title> +<title>Headers and multilib</title> <body> <p> Most C/C++ programs need standard header files like <c>types.h</c>. Some of them depend on architecture specific facts, e.g. <c>types.h</c> on the length -of machine words. To ensure that we can compile both 32bit and 64bit +of machine words. To ensure that we can compile both 32-bit and 64-bit applications and libraries, we treat <c>/usr/include/asm</c> a bit special. </p> @@ -377,25 +277,26 @@ This is what <c>/usr/include/asm/types.h</c> looks like on an AMD64 box: 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"/> -section. +<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"/> section. </p> </body> </subsection> <subsection> -<title>The ABI Variable</title> +<title>The ABI variable</title> <body> <p> -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> -must be appended to CFLAGS. This is done via <c>profile.bashrc</c>. All you need to do -if you want to build a package 32bit is to set <c>ABI=x86</c>. +Whenever Portage builds something on amd64, it has to decide whether it should +be 32-bit or 64-bit. 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> must be +appended to CFLAGS. This is done via <c>profile.bashrc</c>. All you need to do +if you want to build a package 32-bit is to set <c>ABI=x86</c>. </p> <p> @@ -424,10 +325,10 @@ LIBDIR_x86="lib32" </section> <section> -<title>Porting Notes</title> +<title>Porting notes</title> <subsection> -<title>Machine Word sizes</title> +<title>Machine word sizes</title> <body> <p> @@ -574,7 +475,7 @@ segmentation faults or strange behaviour. GCC 4.0 refuses to compile such code. </section> <section> -<title>Other Resources</title> +<title>Other resources</title> <body> <ul> diff --git a/archs/mips/text.xml b/archs/mips/text.xml index 7e6bc06..9e4ca16 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> @@ -64,20 +64,20 @@ between these, talk to the MIPS team. </section> <section> -<title>Not Dropping <c>CFLAGS</c> on MIPS</title> +<title>Not dropping <c>CFLAGS</c> on MIPS</title> <body> <p> Because <c>CFLAGS</c> are sometimes used to specify ISA and ABI information, it is vital that packages honour this setting. See -<uri link="::general-concepts/user-environment/#Not Filtering Variables"/>. +<uri link="::general-concepts/user-environment/#Not filtering variables"/>. </p> </body> </section> <section> -<title>Additional MIPS Keywording Requirements</title> +<title>Additional MIPS keywording requirements</title> <body> <note> @@ -110,7 +110,7 @@ MIPS doesn't currently use stable keywords so don't file stable requests to them </section> <section> -<title>Contacting the MIPS Team</title> +<title>Contacting the MIPS team</title> <body> <p> @@ -128,7 +128,7 @@ 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> diff --git a/archs/ppc/text.xml b/archs/ppc/text.xml index 65fab01..3afb633 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> @@ -62,7 +62,7 @@ code below to define vectors is the preferred way of fixing this: </section> <section> -<title>Contacting the PowerPC Team</title> +<title>Contacting the PowerPC team</title> <body> <p> @@ -71,7 +71,7 @@ The PowerPC team can be reached by: <ul> <li> - Via the <c>#gentoo-powerpc</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> @@ -88,7 +88,7 @@ The PowerPC team can be reached by: </section> <section> -<title>Other Resources</title> +<title>Other resources</title> <body> <ul> @@ -96,7 +96,7 @@ The PowerPC team can be reached by: <uri link="https://wiki.gentoo.org/wiki/PPC/FAQ">Gentoo PPC FAQ</uri> </li> <li> - <uri link="https://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> diff --git a/archs/sparc/text.xml b/archs/sparc/text.xml index 9ce02d8..c828e83 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> @@ -10,10 +10,24 @@ hardware (Sun UltraSparc systems with <c>v9</c> CPUs). <c>v8</c> processors 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> +<title>SPARC kernel and userland ABIs</title> <body> <p> @@ -36,13 +50,13 @@ buses. </section> <section> -<title>Additional SPARC Keywording Requirements</title> +<title>Additional SPARC keywording requirements</title> <body> <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> @@ -66,7 +80,7 @@ the <c>sparc@</c> alias. </section> <section> -<title>SPARC Instruction Set and Performance Notes</title> +<title>SPARC instruction set and performance notes</title> <body> <p> @@ -102,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> @@ -110,7 +124,7 @@ are especially important on SPARC. </section> <section> -<title>Contacting the SPARC Team</title> +<title>Contacting the SPARC team</title> <body> <p> @@ -128,7 +142,7 @@ 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> diff --git a/archs/text.xml b/archs/text.xml index 4eb9750..5df6b24 100644 --- a/archs/text.xml +++ b/archs/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="archs/"> <chapter> -<title>Arch Specific Notes</title> +<title>Arch specific notes</title> <body> <p> diff --git a/archs/x86/text.xml b/archs/x86/text.xml index d6ddad7..59a3f68 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> @@ -20,7 +20,7 @@ unless someone on the team can test it. </body> <section> -<title>x86 Team Guidelines</title> +<title>x86 team guidelines</title> <body> <p> @@ -32,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 @@ -47,7 +47,7 @@ The following is a list of rules and expectations for members of the x86 team: </section> <section> -<title>Contacting the x86 Team</title> +<title>Contacting the x86 team</title> <body> <p> @@ -62,7 +62,7 @@ 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> diff --git a/bin/gen-eclass-html.sh b/bin/gen-eclass-html.sh index 9486852..cdd5244 100755 --- a/bin/gen-eclass-html.sh +++ b/bin/gen-eclass-html.sh @@ -30,11 +30,11 @@ IFS='' read -r -d '' HEADER << 'EOF' <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 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 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> @@ -51,8 +51,8 @@ IFS='' read -r -d '' HEADER << 'EOF' </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> +<li><a href="../../index.html">Master index</a></li> +<li><a href="../index.html">Eclass reference</a></li> </ol> </div></div></div> </header> @@ -70,12 +70,17 @@ IFS='' read -r -d '' FOOTER << 'EOF' </div> </div> <div class="row"> -<div class="col-xs-2 col-sm-3 col-md-2"><ul class="footerlinks three-icons"> +<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> +</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-2021 Gentoo Authors</strong><br><small> +<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>. @@ -123,7 +128,7 @@ shift $((OPTIND-1)) MANPAGES=() [[ -n ${NOMAN} ]] || MANPAGES=( $(/usr/bin/qlist -e eclass-manpages) - # We also need a couple of portage man pages + # We also need a couple of Portage man pages /usr/share/man/man5/ebuild.5* /usr/share/man/man5/make.conf.5* ) || exit 1 @@ -149,6 +154,7 @@ for i in "${MANPAGES[@]}"; do -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' \ @@ -162,10 +168,10 @@ 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"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="eclass-reference/"> <chapter> -<title>Eclass Reference</title> +<title>Eclass reference</title> <body> <p> @@ -1,8 +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="exslt xsl" - exclude-result-prefixes="exslt xsl"> + extension-element-prefixes="str exslt xsl" + exclude-result-prefixes="str exslt xsl"> <xsl:import href="devbook.xsl"/> <xsl:output method="text"/> @@ -20,14 +21,25 @@ <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[. != '#']"> - <!-- At this point, the path can contain ".." components and - should be canonicalised, but string processing in XPath 1.0 - sucks (no pattern matching!). It is easier to pipe the output - through sed instead. --> - <xsl:value-of select="concat(' ', $self, - substring-before(., 'index.html'), 'text.xml')"/> + <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.dtd b/devbook.dtd deleted file mode 100644 index 17fb59b..0000000 --- a/devbook.dtd +++ /dev/null @@ -1,90 +0,0 @@ -<!-- Copyright 2019-2020 Gentoo Authors --> -<!-- Distributed under the terms of the MIT/X11 license --> - -<!-- Document Type Definition for the Gentoo Devmanual --> -<!-- Based on common.dtd from GuideXML --> - -<!ENTITY % block.class "p|pre|codesample|note|important|warning|todo - |figure|table|ul|ol|dl"> -<!ENTITY % attrib.class "b|c|e"> -<!ENTITY % inline.class "%attrib.class;|d|uri"> -<!ENTITY % all.class "%block.class;|%inline.class;"> - -<!ELEMENT guide (chapter, include*)> -<!ATTLIST guide root (true) #IMPLIED - self CDATA #IMPLIED> - -<!ELEMENT include EMPTY> -<!ATTLIST include href CDATA #REQUIRED> - -<!ELEMENT chapter (title, (body|section), section*)> -<!ELEMENT section (title, (body|subsection), subsection*)> -<!ELEMENT subsection (title, (body|subsubsection), subsubsection*)> -<!ELEMENT subsubsection (title, body)> - -<!-- Title texts are used as anchors, so allow only text attributes --> -<!ELEMENT title (#PCDATA|%attrib.class;)*> - -<!ELEMENT body (authors|contentsTree|%block.class;)+> - -<!ELEMENT authors (author)+> -<!ELEMENT author (#PCDATA|%inline.class;)*> -<!ATTLIST author name CDATA #REQUIRED - email CDATA #IMPLIED> - -<!ELEMENT contentsTree EMPTY> -<!ATTLIST contentsTree maxdepth CDATA #IMPLIED - root CDATA #IMPLIED - extraction CDATA #IMPLIED> - -<!ELEMENT p (#PCDATA|%inline.class;)*> - -<!ELEMENT pre (#PCDATA)> - -<!ELEMENT codesample (#PCDATA)> -<!ATTLIST codesample lang (c|ebuild|make|m4|sgml) #REQUIRED - numbering (lines) #IMPLIED> - -<!ELEMENT note (#PCDATA|%inline.class;)*> -<!ELEMENT important (#PCDATA|%inline.class;)*> -<!ELEMENT warning (#PCDATA|%inline.class;)*> -<!ELEMENT todo (#PCDATA|%inline.class;)*> - -<!ELEMENT figure EMPTY> -<!ATTLIST figure link CDATA #REQUIRED - short CDATA #IMPLIED - caption CDATA #IMPLIED> - -<!ELEMENT table (tr)+> - -<!ELEMENT tr (th|ti)+> - -<!ELEMENT th (#PCDATA|%inline.class;)*> -<!ATTLIST th colspan CDATA #IMPLIED - rowspan CDATA #IMPLIED - align (left|center|right) "left"> - -<!ELEMENT ti (#PCDATA|%all.class;)*> -<!ATTLIST ti colspan CDATA #IMPLIED - rowspan CDATA #IMPLIED - nowrap CDATA #IMPLIED - align (left|center|right) "left"> - -<!ELEMENT ul (li)+> -<!ATTLIST ul class CDATA #IMPLIED> - -<!ELEMENT ol (li)+> - -<!ELEMENT li (#PCDATA|%all.class;)*> - -<!ELEMENT dl (dt|dd)+> -<!ELEMENT dt (#PCDATA|%inline.class;)*> -<!ELEMENT dd (#PCDATA|%all.class;)*> - -<!ELEMENT b (#PCDATA|%inline.class;)*> -<!ELEMENT c (#PCDATA|%inline.class;)*> -<!ELEMENT e (#PCDATA|%inline.class;)*> -<!ELEMENT d EMPTY> - -<!ELEMENT uri (#PCDATA|%inline.class;)*> -<!ATTLIST uri link CDATA #IMPLIED> 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 49dc0c3..c9a1a1c 100644 --- a/devbook.xsl +++ b/devbook.xsl @@ -12,7 +12,7 @@ <xsl:import href="xsl/lang.highlight.m4.xsl"/> <xsl:import href="xsl/lang.highlight.sgml.xsl"/> -<xsl:output method="html" encoding="UTF-8" indent="yes" omit-xml-declaration="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". --> @@ -23,361 +23,439 @@ </xsl:text> </xsl:variable> - <xsl:template match="chapter"> - <h1 class="first-header"> +<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=""><span class="fa fa-link"/></a> - </h1> + <a class="permalink" href="#{$anchor}"><span class="fa fa-link"/></a> + </xsl:element> <xsl:apply-templates select="*[not(self::title)]"/> - </xsl:template> - - <xsl:template match="section|subsection|subsubsection"> - <xsl:variable name="level"> - <xsl:value-of select="number(starts-with(local-name(), 'sub')) - + number(starts-with(local-name(), 'subsub')) + 2"/> - </xsl:variable> - <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> + </div> +</xsl:template> - <xsl:template match="p"> - <p> +<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> - <!-- 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"> +<!-- 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:attribute name="nowrap"><xsl:value-of select="@nowrap"/></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 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> - <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:apply-templates/></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:attribute name="style">text-align:center;</xsl:attribute> </xsl:when> - <xsl:otherwise> - <ul><xsl:apply-templates/></ul> - </xsl:otherwise> </xsl:choose> - </xsl:template> + <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="@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:attribute> + </xsl:if> + <xsl:apply-templates/> + </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> - <!-- Definition Lists --> - <xsl:template match="dl"> - <dl><xsl:apply-templates/></dl> - </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="dt"> + <dt><xsl:apply-templates/></dt> +</xsl:template> - <xsl:template match="dd"> - <dd><xsl:apply-templates/></dd> - </xsl:template> +<xsl:template match="dd"> + <dd><xsl:apply-templates/></dd> +</xsl:template> - <xsl:template match="note"> - <div class="alert alert-info" role="alert"> - <strong>Note:</strong> +<xsl:template match="note"> + <div class="alert alert-info" role="alert"> + <strong>Note:</strong><xsl:text> </xsl:text> <xsl:apply-templates/> - </div> - </xsl:template> + </div> +</xsl:template> - <xsl:template match="important"> - <div class="alert alert-warning" role="alert"> - <strong>Important:</strong> +<xsl:template match="important"> + <div class="alert alert-warning" role="alert"> + <strong>Important:</strong><xsl:text> </xsl:text> <xsl:apply-templates/> - </div> - </xsl:template> + </div> +</xsl:template> - <xsl:template match="warning"> - <div class="alert alert-danger" role="alert"> - <strong>Warning:</strong> +<xsl:template match="warning"> + <div class="alert alert-danger" role="alert"> + <strong>Warning:</strong><xsl:text> </xsl:text> <xsl:apply-templates/> - </div> - </xsl:template> + </div> +</xsl:template> - <xsl:template match="todo"> - <div class="alert alert-info" role="alert"> - <strong>Todo:</strong> +<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> - </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 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 match="uri"> - <xsl:param name="class" /> - <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> + </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, '##')"> - <xsl:variable name="slash"> - <xsl:if test="substring(substring-before(@link, '##'), string-length(substring-before(@link, '##'))) != '/'">/</xsl:if> - </xsl:variable> - <a class="{$class}" href="{concat($relative_path_depth_recursion, substring-after(substring-before(@link, '##'), '::'), $slash, '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 class="{$class}" 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 class="{$class}" 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 class="{$class}" 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(@link, '::eclass-reference/') and substring-after(@link, '::eclass-reference/') != ''"> + <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 --> - <a class="{$class}" href="{concat($relative_path_depth_recursion, substring-after(@link, '::'), $slash, 'index.html')}"><xsl:value-of select="substring-before(concat(substring-after(@link, '::eclass-reference/'), $slash), '/')"/></a> + <xsl:value-of select="substring-before(substring-after($path, '/'), '/')"/> </xsl:when> <xsl:otherwise> - <a class="{$class}" 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:when test="@link"> - <a class="{$class}" href="{@link}"><xsl:value-of select="."/></a> - </xsl:when> - <xsl:when test="contains(., '://')"> - <a class="{$class}" href="{.}"><xsl:value-of select="."/></a> - </xsl:when> - <xsl:otherwise> - <xsl:message>Error: No link target (<xsl:value-of select="."/>)</xsl:message> - <a class="{$class}"><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> + </a> + </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)}"> + <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> @@ -393,49 +471,61 @@ <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: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]"/></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> + <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="/"> - <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:text disable-output-escaping='yes'><!DOCTYPE html></xsl:text> - <xsl:value-of select='$newline'/> - <html lang="en"> + </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><xsl:value-of select="/guide/chapter[1]/title"/> – Gentoo Development Guide</title> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> @@ -480,11 +570,11 @@ <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 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"></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> @@ -505,7 +595,8 @@ <div class="container"> <div class="row"> <div class="navbar-header"> - <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-main-collapse"> + <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> @@ -514,9 +605,11 @@ </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> + <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> + <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. --> @@ -555,9 +648,11 @@ <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()"/> + <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()"/> + <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> @@ -615,14 +710,26 @@ <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-2021 Gentoo Authors</strong><br /> + <strong>Copyright (C) 2001-2024 Gentoo Authors</strong><br /> <small> - Gentoo is a trademark of the Gentoo Foundation, Inc. + 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 - <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>. + <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/">CC-BY-SA-4.0</a> license. + </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> @@ -633,189 +740,202 @@ <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><xsl:text>var documentsSrc = "</xsl:text><xsl:value-of select="$relative_path_depth_recursion"/><xsl:text>documents.js"</xsl:text></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 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> - <!-- 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 class="w-250 text-center" href="{concat($relative_path_depth_recursion, $relative_path, 'index.html')}"> <span class="truncated-text d-inline-block max-w-200 mr-2"><xsl:value-of select="document(concat($parentItem_actual, '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_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 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> - <!-- 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: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: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('../', substring-before($myItem_path, 'text.xml'), '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))/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: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="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:call-template name="printParentDocs"> - <xsl:with-param name="depth" select="$depth - 1"/> + </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: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 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: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: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/ebuild-maintenance/git/text.xml b/ebuild-maintenance/git/text.xml index 5240f6a..6ad3837 100644 --- a/ebuild-maintenance/git/text.xml +++ b/ebuild-maintenance/git/text.xml @@ -1,9 +1,9 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-maintenance/git/"> <chapter> -<title>Git for Gentoo Developers</title> - +<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. @@ -90,9 +90,9 @@ graft it into the repository: </p> <pre> -git remote add history https://anongit.gentoo.org/git/repo/gentoo/historical.git/ +git remote add history https://anongit.gentoo.org/git/archive/repo/gentoo-2.git git fetch history -git replace --graft 56bd759df1d0c750a065b8c845e93d5dfa6b549d history/master +git replace --graft 56bd759df1d0c750a065b8c845e93d5dfa6b549d cvs-final-2015-08-08 </pre> <p> @@ -112,11 +112,10 @@ the historical commits after the initial git commit. <body> <p> -The recommended way of committing to the Gentoo repository is to use <c>repoman -commit</c>. It automatically performs the necessary QA checks on the package -being committed and has other features helping with the Gentoo workflow. -However, it is currently limited to creating a single commit to a single -package. +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> @@ -125,23 +124,27 @@ 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>repoman commit</c> with additional files -or fixups,</li> -<li>combining multiple commits created via <c>repoman commit</c> using <c>git -rebase</c>.</li> + <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 repoman is not used to commit, you need to manually verify all -packages affected by the commit using <c>repoman full</c>. Since repoman -is not aware of staged changes, please make sure that all files are included -in the commit. Also when not using repoman, you must perform a manual sign-off -to the <uri link="https://www.gentoo.org/glep/glep-0076.html#certificate-of-origin"> -Certificate of Origin</uri> 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. +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> @@ -157,28 +160,26 @@ 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> + <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> @@ -192,7 +193,7 @@ in the first commit in the series introduced by a single push. </subsection> <subsection> -<title>Git Commit Message Format</title> +<title>Git commit message format</title> <body> <p> @@ -219,13 +220,15 @@ appropriately: </p> <ul> -<li><c>${CATEGORY}/${PN}:</c>Single Package (Note that <c>repoman commit</c> -automatically inserts 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> + <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> @@ -265,28 +268,25 @@ 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> -<li><c>Package-Manager:</c> This is automatically inserted by -<c>repoman commit</c> and it specifies the version of -<c>sys-apps/portage</c> on the system.</li> -<li><c>RepoMan-Options:</c> This is automatically inserted by -<c>repoman commit</c> and records the options passed to repoman (such -as --force) for the commit.</li> + <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 +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. diff --git a/ebuild-maintenance/new-ebuild/text.xml b/ebuild-maintenance/new-ebuild/text.xml index ad7f74c..e79d30c 100644 --- a/ebuild-maintenance/new-ebuild/text.xml +++ b/ebuild-maintenance/new-ebuild/text.xml @@ -1,22 +1,23 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-maintenance/new-ebuild/"> <chapter> -<title>Adding a New Ebuild</title> +<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>ebuilds</e>. In the search field put the name of the ebuild and as status -select all possible fields, then submit the query. For you lazy people, click -<uri link="https://bugs.gentoo.org/query.cgi?format=advanced&product=Gentoo%20Linux&component=New%20Ebuilds&bug_Status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=IN_PROGRESS&bug_status=RESOLVED&bug_status=VERIFIED">here</uri>. +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> @@ -24,9 +25,15 @@ 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. Larger patch files should be placed -in your developer space on <c>dev.gentoo.org</c> instead, in order to minimize -the repository size. +<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> @@ -48,16 +55,17 @@ examples. </p> <p> -When committing to git, all developers should use <c>repoman commit</c> -instead of <c>git commit</c> to submit their ebuilds. Before committing, -please run <c>repoman full</c> to make sure you didn't forget something. +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> +<title>Initial architecture keywords</title> <body> <p> @@ -83,7 +91,7 @@ work on those architectures. </section> <section> -<title>The files Directory</title> +<title>The files directory</title> <body> <p> @@ -94,8 +102,8 @@ 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.diff</c>, or more -simply, <c>1.0-gentoo.diff</c>. Also note that the +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 diff --git a/ebuild-maintenance/package-moves/text.xml b/ebuild-maintenance/package-moves/text.xml index 21cd245..801dada 100644 --- a/ebuild-maintenance/package-moves/text.xml +++ b/ebuild-maintenance/package-moves/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-maintenance/package-moves/"> <chapter> -<title>Package and Slot Moves</title> +<title>Package and slot moves</title> <body> <p> @@ -12,14 +12,17 @@ the following must be noted: <ol> <li> - Updates 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. + <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. Attempting to reuse it will cause updates to apply again, - to the reused name. This also means that updates cannot be undone. + 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 @@ -35,18 +38,19 @@ the following must be noted: <body> <p> -Moving or renaming a package 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 +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: +to <c>profiles/updates/</c> in the following format: </p> <pre> @@ -60,9 +64,9 @@ and update them. These include: <ul> <li> - <uri link="::general-concepts/dependencies">dependencies</uri>, - <c>has_version</c> and <c>best_version</c> uses in other ebuilds - and eclasses + <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>) @@ -77,6 +81,9 @@ and update them. These include: <li> open bug summaries </li> + <li> + wiki pages + </li> </ul> <p> @@ -92,8 +99,8 @@ during the update. <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 +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> @@ -110,5 +117,49 @@ happens to contain an entry which may be affected by your change. </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 index 8fb9f50..f012528 100644 --- a/ebuild-maintenance/removal/text.xml +++ b/ebuild-maintenance/removal/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-maintenance/removal/"> <chapter> -<title>Removing Ebuilds and Packages</title> +<title>Removing ebuilds and packages</title> <section> <title>Removing ebuilds</title> @@ -52,10 +52,10 @@ When removing packages follow these steps: <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> + <uri link="::ebuild-writing/misc-files/metadata/">metadata.xml</uri> files of other packages. </li> - <li>Close open bugs as WONTFIX</li> + <li>Close open bugs as PKGREMOVED</li> </ol> <p> @@ -113,10 +113,8 @@ In order to remove a virtual package, follow the following procedure: Wait the time appropriate for the last rites. </li> <li> - Update all ebuilds not to reference the virtual. Since there is - no urgent need to remove the virtual from user systems - and the resulting rebuilds would be unnecessary, do not bump ebuilds - when replacing the dependency. + Update all ebuilds not to reference the virtual, following normal + <uri link="::general-concepts/ebuild-revisions/"/> policy </li> <li> Remove the package directly diff --git a/ebuild-maintenance/text.xml b/ebuild-maintenance/text.xml index 270230e..0796227 100644 --- a/ebuild-maintenance/text.xml +++ b/ebuild-maintenance/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-maintenance/"> <chapter> -<title>Ebuild Maintenance</title> +<title>Ebuild maintenance</title> <body> <p> diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index 85c0e3f..134990c 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/common-mistakes/"> <chapter> -<title>Common Mistakes</title> +<title>Common mistakes</title> <body> <p> @@ -11,15 +11,29 @@ writing ebuilds. </body> <section> -<title>Common Ebuild Writing Mistakes</title> +<title>Common ebuild writing mistakes</title> <subsection> -<title>Invalid use of <c>static</c> use-flag</title> +<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> @@ -30,12 +44,15 @@ install static libraries. Instead, the <c>static-libs</c> use-flag is used for t <p> The usage of <c>ROOT</c> is only designed to influence the way the package is 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. +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> @@ -77,26 +94,37 @@ someone reports a bug for your package, the <b>build log must always be verbose. <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). -</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> @@ -104,32 +132,43 @@ preferred.</note> <title>-Werror compiler flag not removed</title> <body> <p> -"-Werror" is a flag which turns all warnings into errors and thus will abort compiling if any warning is encountered. +"-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> <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.: +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> <p> -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. +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> @@ -138,10 +177,16 @@ 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> @@ -150,7 +195,14 @@ Always check that it's really gone in the build log. <p><b>Specific -Werror=... flags</b></p> <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. +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> @@ -165,7 +217,7 @@ the resulting Makefile. </subsection> <subsection> -<title>Missing/Invalid/Broken Header</title> +<title>Missing/invalid/broken header</title> <body> <p> @@ -187,12 +239,12 @@ The first two lines <e>must</e> look like this: </body> </subsection> <subsection> -<title>Redefined P, PV, PN, PF</title> +<title>Redefined P, PV, PN, PF variables</title> <body> <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> @@ -262,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 @@ -295,14 +352,14 @@ some tips on how to find the correct dependencies. 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> </body> </subsection> <subsection> -<title>LICENSE Invalid</title> +<title>LICENSE invalid</title> <body> <p> @@ -337,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> @@ -356,23 +427,27 @@ SLOT="0" <body> <p> +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. And make sure -the <c>DESCRIPTION</c> is not overly long. Good descriptions will describe -the main function of the package in a sentence. If no homepage for the package -is available, set the <c>HOMEPAGE</c> variable to -<c>https://wiki.gentoo.org/wiki/No_homepage</c>. +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> </subsection> <subsection> -<title>Wrongfully used spaces instead of TABS</title> +<title>Wrongfully used spaces instead of TABs</title> <body> <p> It is no fun reformatting lines of ebuilds because the submitter did not follow -the guidelines to use TABS rather than spaces. So <e>please</e> use tabs! +the guidelines to use TABs rather than spaces. So <e>please</e> use TABs! </p> </body> @@ -382,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> @@ -433,11 +508,46 @@ at least when the ebuild hits the stable branch. </p> </body> </subsection> -</section> +<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> +<title>Common ebuild submission mistakes</title> <subsection> <title>Introduction</title> <body> @@ -450,7 +560,7 @@ Please submit ebuilds properly by following the </body> </subsection> <subsection> -<title>Tarball'ing an ebuild</title> +<title>Tarballing an ebuild</title> <body> <p> @@ -461,7 +571,7 @@ operations when reviewing. </body> </subsection> <subsection> -<title>Inlining Ebuilds</title> +<title>Inlining ebuilds</title> <body> <p> @@ -497,7 +607,7 @@ The best way to generate it would be: </p> <pre> -$ diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-package-0.2.0.diff +$ diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-package-0.2.0.patch </pre> </body> @@ -507,7 +617,7 @@ $ diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-packag <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 b738640..26795cf 100644 --- a/ebuild-writing/eapi/text.xml +++ b/ebuild-writing/eapi/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/eapi/"> <chapter> -<title>EAPI Usage and Description</title> +<title>EAPI usage and description</title> <body> <p> @@ -62,8 +62,39 @@ EAPI-conditional code) 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> + +<subsection> +<title>Upgrade path</title> +<body> + +<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> + +<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> + +<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> @@ -82,7 +113,7 @@ Manager Specification for details about them. <title>EAPI 5</title> <subsection> -<title>EAPI 5 Metadata</title> +<title>EAPI 5 metadata</title> <body> <dl> @@ -175,7 +206,7 @@ RDEPEND="dev-libs/foo:2= </subsection> <subsection> -<title>EAPI 5 Profiles</title> +<title>EAPI 5 profiles</title> <body> <dl> @@ -193,7 +224,7 @@ RDEPEND="dev-libs/foo:2= </subsection> <subsection> -<title>EAPI 5 Helpers</title> +<title>EAPI 5 helpers</title> <body> <dl> @@ -232,7 +263,7 @@ If USE flag is set, echo [true output][true suffix] (defaults to "yes"), </subsection> <subsection> -<title>EAPI 5 Phases</title> +<title>EAPI 5 phases</title> <body> <dl> @@ -247,7 +278,7 @@ If USE flag is set, echo [true output][true suffix] (defaults to "yes"), </subsection> <subsection> -<title>EAPI 5 Variables</title> +<title>EAPI 5 variables</title> <body> <dl> @@ -281,7 +312,7 @@ If USE flag is set, echo [true output][true suffix] (defaults to "yes"), </subsection> <subsection> -<title>EAPI 6 Ebuild Environment</title> +<title>EAPI 6 ebuild environment</title> <body> <dl> @@ -303,7 +334,7 @@ If USE flag is set, echo [true output][true suffix] (defaults to "yes"), </subsection> <subsection> -<title>EAPI 6 Phases</title> +<title>EAPI 6 phases</title> <body> <dl> @@ -346,7 +377,7 @@ src_install() { </subsection> <subsection> -<title>EAPI 6 Helpers</title> +<title>EAPI 6 helpers</title> <body> <dl> @@ -426,7 +457,7 @@ src_install() { <title>EAPI 7</title> <subsection> -<title>EAPI 7 Terminology</title> +<title>EAPI 7 terminology</title> <body> <p> @@ -454,7 +485,7 @@ installation targets. </subsection> <subsection> -<title>EAPI 7 Variables</title> +<title>EAPI 7 variables</title> <body> <dl> @@ -504,7 +535,7 @@ installation targets. </subsection> <subsection> -<title>EAPI 7 Metadata</title> +<title>EAPI 7 metadata</title> <body> <dl> @@ -522,7 +553,7 @@ installation targets. </subsection> <subsection> -<title>EAPI 7 Profiles</title> +<title>EAPI 7 profiles</title> <body> <dl> @@ -537,7 +568,7 @@ installation targets. </subsection> <subsection> -<title>EAPI 7 Helpers</title> +<title>EAPI 7 helpers</title> <body> <dl> @@ -573,7 +604,7 @@ installation targets. <li><c>ver_test</c> compares two versions</li> </ul> <p> - See <uri link="::ebuild-writing/variables/#Version and Name Formatting Issues"/> + 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> @@ -619,5 +650,771 @@ installation targets. </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>EAPI 8 tree layout</title> +<body> + +<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> +</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/error-handling/text.xml b/ebuild-writing/error-handling/text.xml index f74f6d8..28dca4e 100644 --- a/ebuild-writing/error-handling/text.xml +++ b/ebuild-writing/error-handling/text.xml @@ -1,10 +1,10 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/error-handling/"> <chapter> -<title>Error Handling</title> +<title>Error handling</title> <section> -<title>Importance of Error Handling</title> +<title>Importance of error handling</title> <body> <p> @@ -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> @@ -32,7 +32,7 @@ Decent error handling is important because: </section> <section> -<title>The <c>die</c> Function</title> +<title>The <c>die</c> function</title> <body> <p> @@ -54,17 +54,18 @@ the <uri link="::eclass-reference/">eclass reference</uri> when in doubt. <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> <section> -<title><c>die</c> and Subshells</title> +<title><c>die</c> and subshells</title> <body> <warning> @@ -95,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> @@ -104,20 +105,20 @@ 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> </section> <section> -<title>The <c>assert</c> Function and <c>$PIPESTATUS</c></title> +<title>The <c>assert</c> function and <c>$PIPESTATUS</c></title> <body> <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> @@ -135,7 +136,7 @@ time, <c>assert</c> is enough. </section> <section> -<title>The <c>nonfatal</c> Command</title> +<title>The <c>nonfatal</c> command</title> <body> <p> diff --git a/ebuild-writing/file-format/text.xml b/ebuild-writing/file-format/text.xml index 2bd6623..bca3dad 100644 --- a/ebuild-writing/file-format/text.xml +++ b/ebuild-writing/file-format/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/file-format/"> <chapter> -<title>Ebuild File Format</title> +<title>Ebuild file format</title> <body> <p> @@ -11,7 +11,7 @@ Files should be simple text files with a <c>.ebuild</c> extension. </body> <section> -<title>File Naming Rules</title> +<title>File naming rules</title> <body> <p> @@ -42,12 +42,12 @@ 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> @@ -102,12 +102,13 @@ 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> @@ -115,11 +116,19 @@ Overall, this gives us a filename like <c>libfoo-1.2.5b_pre5-r2.ebuild</c>. </p> <p> -The <uri link ="::ebuild-writing/variables/#Version and Name Formatting Issues"> +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> @@ -127,17 +136,20 @@ ebuild version components. <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. +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). +(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> @@ -166,7 +178,7 @@ like CPU time or memory when being built from source. </section> <section> -<title>Ebuild Header</title> +<title>Ebuild header</title> <body> <p> @@ -178,7 +190,7 @@ header.txt</uri></c> in the top directory of the Gentoo repository. </p> <codesample lang="ebuild"> -# Copyright 1999-2021 Gentoo Authors +# Copyright 1999-2024 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 </codesample> @@ -193,7 +205,7 @@ Council on 28 February 2017</uri> and <e>must not</e> be added any more. </section> <section> -<title>Indenting and Whitespace</title> +<title>Indenting and whitespace</title> <body> <p> @@ -203,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> @@ -218,10 +230,10 @@ positions wide, and multibyte characters are just one position wide. </section> <section> -<title>Character Set</title> +<title>Character set</title> <body> <p> -All ebuilds (and eclasses, metadata files and ChangeLogs) must use the +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. diff --git a/ebuild-writing/functions/pkg_config/text.xml b/ebuild-writing/functions/pkg_config/text.xml index ce97bd8..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,8 +32,7 @@ <title>Default <c>pkg_config</c></title> <body> <codesample lang="ebuild"> -pkg_config() -{ +pkg_config() { eerror "This ebuild does not have a config function." } </codesample> @@ -49,7 +48,7 @@ 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 + 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 diff --git a/ebuild-writing/functions/pkg_info/text.xml b/ebuild-writing/functions/pkg_info/text.xml index c6e0432..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,8 +32,7 @@ <title>Default <c>pkg_info</c></title> <body> <codesample lang="ebuild"> -pkg_info() -{ +pkg_info() { return } </codesample> diff --git a/ebuild-writing/functions/pkg_nofetch/text.xml b/ebuild-writing/functions/pkg_nofetch/text.xml index 036ad62..292c447 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" + elog "The following files cannot be fetched for ${PN}:" + local x + for x in ${A}; do + elog " ${x}" done - return } </codesample> </body> @@ -68,8 +67,8 @@ be referenced. <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 833dfe4..7a160a5 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,8 +32,7 @@ <title>Default <c>pkg_postinst</c></title> <body> <codesample lang="ebuild"> -pkg_postinst() -{ +pkg_postinst() { return } </codesample> @@ -45,7 +44,7 @@ pkg_postinst() <body> <codesample lang="ebuild"> pkg_postinst() { - if $OLD_FLUXBOX_VERSION ; then + 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 " " @@ -59,7 +58,7 @@ pkg_postinst() { </section> <section> -<title>Common <c>pkg_postinst</c> Tasks</title> +<title>Common <c>pkg_postinst</c> tasks</title> <body> <p> The most common use for <c>pkg_postinst</c> is to display post-install diff --git a/ebuild-writing/functions/pkg_postrm/text.xml b/ebuild-writing/functions/pkg_postrm/text.xml index 3efaabf..6607b37 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,8 +32,7 @@ <title>Default <c>pkg_postrm</c></title> <body> <codesample lang="ebuild"> -pkg_postrm() -{ +pkg_postrm() { return } </codesample> @@ -44,6 +43,8 @@ pkg_postrm() <title>Sample <c>pkg_postrm</c></title> <body> <codesample lang="ebuild"> +inherit xdg-utils + pkg_postrm() { xdg_desktop_database_update xdg_mimeinfo_database_update @@ -53,7 +54,7 @@ pkg_postrm() { </section> <section> -<title>Common <c>pkg_postrm</c> Tasks</title> +<title>Common <c>pkg_postrm</c> tasks</title> <body> <p> <c>pkg_postrm</c> is is used to update symlinks, cache files and other diff --git a/ebuild-writing/functions/pkg_preinst/text.xml b/ebuild-writing/functions/pkg_preinst/text.xml index a68950f..cb3a9ab 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,8 +32,7 @@ <title>Default <c>pkg_preinst</c></title> <body> <codesample lang="ebuild"> -pkg_preinst() -{ +pkg_preinst() { return } </codesample> @@ -53,7 +52,7 @@ pkg_preinst() { </section> <section> -<title>Common <c>pkg_preinst</c> Tasks</title> +<title>Common <c>pkg_preinst</c> tasks</title> <body> <p> There are a few things that are often done in <c>pkg_preinst</c>: @@ -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 7e05b0e..9ce88f4 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,8 +32,7 @@ <title>Default <c>pkg_prerm</c></title> <body> <codesample lang="ebuild"> -pkg_prerm() -{ +pkg_prerm() { return } </codesample> @@ -53,7 +52,7 @@ pkg_prerm() { </section> <section> -<title>Common <c>pkg_prerm</c> Tasks</title> +<title>Common <c>pkg_prerm</c> tasks</title> <body> <p> <c>pkg_prerm</c> is used to clean up any files that would otherwise prevent diff --git a/ebuild-writing/functions/pkg_pretend/text.xml b/ebuild-writing/functions/pkg_pretend/text.xml index 89eb269..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> @@ -36,8 +36,7 @@ <title>Default <c>pkg_pretend</c></title> <body> <codesample lang="ebuild"> -pkg_pretend() -{ +pkg_pretend() { return } </codesample> diff --git a/ebuild-writing/functions/pkg_setup/text.xml b/ebuild-writing/functions/pkg_setup/text.xml index 0304d3a..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,8 +32,7 @@ <title>Default <c>pkg_setup</c></title> <body> <codesample lang="ebuild"> -pkg_setup() -{ +pkg_setup() { return } </codesample> diff --git a/ebuild-writing/functions/src_compile/build-environment/text.xml b/ebuild-writing/functions/src_compile/build-environment/text.xml index fc314cc..de9bea7 100644 --- a/ebuild-writing/functions/src_compile/build-environment/text.xml +++ b/ebuild-writing/functions/src_compile/build-environment/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>Configuring build environment</title> <body> <p> @@ -18,12 +18,12 @@ Except where otherwise specified, any function which operates on <p> Ebuilds must not simply ignore user CFLAGS, CXXFLAGS or LDFLAGS <d/> see -<uri link="::general-concepts/user-environment#Not Filtering Variables"/>. +<uri link="::general-concepts/user-environment/#Not filtering variables"/>. </p> </body> <section> -<title>Guidelines for Flag Filtering</title> +<title>Guidelines for flag filtering</title> <body> <p> @@ -59,7 +59,7 @@ line in the correct place. </section> <section> -<title>Simple Flag Stripping</title> +<title>Simple flag stripping</title> <body> <p> @@ -94,7 +94,7 @@ conservative set of flags. </section> <section> -<title>Flag Replacement</title> +<title>Flag replacement</title> <body> <p> @@ -124,7 +124,7 @@ the flags to be replaced. </section> <section> -<title>Adding Additional Flags</title> +<title>Adding additional flags</title> <body> <p> Sometimes it is necessary to add in additional <c>CFLAGS</c> diff --git a/ebuild-writing/functions/src_compile/building/text.xml b/ebuild-writing/functions/src_compile/building/text.xml index 696dacf..96aeef8 100644 --- a/ebuild-writing/functions/src_compile/building/text.xml +++ b/ebuild-writing/functions/src_compile/building/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>Building a package</title> <body> <p> @@ -20,15 +20,15 @@ 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> <section> -<title>Fixing Compiler Usage</title> +<title>Fixing compiler usage</title> <body> <p> @@ -39,6 +39,15 @@ 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> It is <e>not</e> correct to use the <c>${CC}</c> variable for this purpose. </note> @@ -59,8 +68,8 @@ src_prepare() { # We have a weird Makefile to work with which ignores our # compiler preferences. yay! - # Note the single quotes. - sed -i -e 's:cc -O2:$(CC) $(CFLAGS) $(LDFLAGS):' Makefile \ + # 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..." } @@ -68,7 +77,10 @@ src_compile() { # -Os not happy replace-flags -Os -O2 - emake CC="$(tc-getCC)" CFLAGS="${CFLAGS}" LDFLAGS="${LDFLAGS}" + emake CC="$(tc-getCC)" \ + CPPFLAGS="${CPPFLAGS}" \ + CFLAGS="${CFLAGS}" \ + LDFLAGS="${LDFLAGS}" } </codesample> 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 aef02ac..b5d6191 100644 --- a/ebuild-writing/functions/src_compile/no-build-system/text.xml +++ b/ebuild-writing/functions/src_compile/no-build-system/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>No build system</title> <body> <p> @@ -29,8 +29,8 @@ src_compile() { for x in asclock parser symbols config do $(tc-getCC) \ - ${CFLAGS} ${CPPFLAGS} \ - -I/usr/include \ + ${CPPFLAGS} ${CFLAGS} ${ASFLAGS} \ + -I"${EPREFIX}"/usr/include \ -Dlinux \ -D_POSIX_C_SOURCE=199309L \ -D_POSIX_SOURCE \ @@ -45,8 +45,8 @@ src_compile() { ${LDFLAGS} \ -o asclock \ asclock.o parser.o symbols.o config.o \ - -L/usr/lib \ - -L/usr/lib/X11 \ + -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 35f6285..a74bbc2 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> @@ -36,7 +36,7 @@ <li> <codesample lang="ebuild"> src_compile() { - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then emake || die "emake failed" fi } @@ -72,7 +72,7 @@ src_compile() { </section> <section> -<title><c>src_compile</c> Processes</title> +<title><c>src_compile</c> processes</title> <body> <p> The following subsections cover different topics which often occur when writing diff --git a/ebuild-writing/functions/src_configure/configuring/text.xml b/ebuild-writing/functions/src_configure/configuring/text.xml index 86657bc..f7b3076 100644 --- a/ebuild-writing/functions/src_configure/configuring/text.xml +++ b/ebuild-writing/functions/src_configure/configuring/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>Configuring a package</title> <body> <p> @@ -32,16 +32,16 @@ where appropriate, be used to generate these switches. src_configure() { # We have optional perl, python and ruby support econf \ - $(use_enable perl ) \ - $(use_enable python ) \ - $(use_enable ruby ) + $(use_enable perl) \ + $(use_enable python) \ + $(use_enable ruby) } src_configure() { # Our package optional IPv6 support which uses --with rather than # --enable / --disable - econf $(use_with ipv6 ) + econf $(use_with ipv6) } </codesample> @@ -56,15 +56,15 @@ argument forms: src_configure() { # Our package has optional perl, python and ruby support econf \ - $(use_enable perl perlinterp ) \ - $(use_enable python pythoninterp ) \ - $(use_enable ruby rubyinterp ) + $(use_enable perl perlinterp) \ + $(use_enable python pythoninterp) \ + $(use_enable ruby rubyinterp) # ... } src_configure() { - econf $(use_with X x11 ) + econf $(use_with X x11) } </codesample> @@ -75,7 +75,7 @@ form can be used. </body> <section> -<title><c>econf</c> Options</title> +<title><c>econf</c> options</title> <body> <p> diff --git a/ebuild-writing/functions/src_configure/text.xml b/ebuild-writing/functions/src_configure/text.xml index dca2042..50ccc42 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> @@ -49,20 +49,29 @@ 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 econf \ - $(use_enable ssl ) \ - $(use_enable perl perlinterp ) + $(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> <section> -<title><c>src_configure</c> Processes</title> +<title><c>src_configure</c> processes</title> <body> <p> The following subsections cover different topics which often occur when writing diff --git a/ebuild-writing/functions/src_install/docompress/text.xml b/ebuild-writing/functions/src_install/docompress/text.xml index 93478b4..adaef2b 100644 --- a/ebuild-writing/functions/src_install/docompress/text.xml +++ b/ebuild-writing/functions/src_install/docompress/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_install/docompress/"> <chapter> -<title>Controllable Compression</title> +<title>Controllable compression</title> <body> <p> diff --git a/ebuild-writing/functions/src_install/text.xml b/ebuild-writing/functions/src_install/text.xml index 6ad3412..85cfa6e 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> @@ -84,7 +84,7 @@ src_install() { </section> <section> -<title>Easy Installs</title> +<title>Easy installs</title> <body> <p> Often, especially with autotools-powered packages, there is a <c>Makefile</c> @@ -120,17 +120,16 @@ 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 -install <c>COPYING</c> regardless, if it explains how different -licenses are applied to different parts of the application, for -example. +There is no need for <c>dodoc COPYING</c>! The license belongs in the +repository's <c>licenses/</c> directory. Sometimes though, you might want to +install <c>COPYING</c> regardless, if it explains how different licenses are +applied to different parts of the application, for example. </note> </body> </section> <section> -<title>Trivial Installs</title> +<title>Trivial installs</title> <body> <p> @@ -147,7 +146,7 @@ compilation required) themes: <p> Or sometimes a combination of <c>insinto</c> and <c>doins</c> (plus related -functions <d/> see <uri link="::function-reference/install-functions"/>) <d/> +functions <d/> see <uri link="::function-reference/install-functions/"/>) <d/> the following is based upon the <c>sys-fs/udev</c> install: </p> @@ -210,7 +209,7 @@ simple <c>Makefile</c> driven install. </section> <section> -<title>Other Installs</title> +<title>Other installs</title> <body> <p> Sometimes, there will be a <c>Makefile</c> that does not @@ -222,7 +221,7 @@ upstream explaining the situation to them. </section> <section> -<title><c>src_install</c> Processes</title> +<title><c>src_install</c> processes</title> <body> <p> 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/eapply/text.xml b/ebuild-writing/functions/src_prepare/eapply/text.xml new file mode 100644 index 0000000..97f4445 --- /dev/null +++ b/ebuild-writing/functions/src_prepare/eapply/text.xml @@ -0,0 +1,136 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-writing/functions/src_prepare/eapply/"> +<chapter> +<title>Patching with eapply</title> +<body> + +<p> +The canonical way of applying patches in ebuilds is to use the package +manager's <c>eapply</c> command, either by calling it explicitly, or by +assigning the <c>PATCHES</c> variable supported by the default +<c>src_prepare</c> implementation. +</p> + +<important> +Applying patches to the sources from the upstream tarball is <e>strongly</e> +preferred to distributing your own modified tarball. +</important> + +<p> +The <c>eapply</c> command takes one or more regular file or directory paths as +its arguments. Optionally, these can be preceded by GNU <c>patch</c> options. +</p> + +<note> +The <c>--</c> delimiter indicates the end of options. This is useful if a +filename begins with a hyphen. +</note> + +<ul> + <li> + If an argument is a regular file, it will be applied in the working + directory by calling GNU <c>patch</c> with patch level <c>-p1</c>. + Specifying an explicit <c>-p<e>N</e></c> option will override the default + patch level. + </li> + <li> + For a directory, <c>eapply</c> applies all patch files with names ending + in <c>.diff</c> or <c>.patch</c> in that directory, in POSIXbetical order + of their names. Any other files in the directory are ignored. + Again, <c>-p<e>N</e></c> can be used to override the default <c>-p1</c> + patch level. Note that <c>eapply</c> will not recurse into subdirectories. + </li> +</ul> + +<p> +<c>eapply</c> was added in EAPI 6. It differs from the previously available +<c>epatch</c> in several ways: +</p> + +<ul> + <li> + <c>eapply</c> will not unpack patches for you. + </li> + <li> + The patch level is no longer detected automatically. Patch levels other + than <c>-p1</c> must be specified manually. + </li> + <li> + When specifying a directory, at least one file with a name ending in + <c>.diff</c> or <c>.patch</c> must exist or the command fails. + </li> +</ul> +</body> + +<section> +<title>Basic <c>eapply</c></title> +<body> + +<p> +In its simplest form, <c>eapply</c> takes a single filename and applies that +patch. It will automatically <c>die</c> if the apply fails. The following is +taken from <c>sys-libs/gpm</c>: +</p> + +<codesample lang="ebuild"> + eapply "${FILESDIR}"/${P}-musl.patch +</codesample> + +<p> +In the following simplified example taken from <c>www-client/firefox</c>, +a patchset is added to <c>SRC_URI</c> in order to fetch and unpack it. +<c>eapply</c> is then called with a directory argument. It applies all patches +found in that directory: +</p> + +<codesample lang="ebuild"> +SRC_URI+="https://dev.gentoo.org/~larry/patchsets/${P}-patches-01.tar.xz" + +src_prepare() { + eapply "${WORKDIR}/firefox-patches" + eapply_user +} +</codesample> + +<p> +The <uri link="::ebuild-writing/misc-files/patches/"/> chapter gives some +guidelines about where patches should be hosted and about their formatting. +</p> + +<p> +The default <c><uri link="::ebuild-writing/functions/src_prepare"/></c> +function will look for a global PATCHES array to apply a list of patches +for you. +</p> + +<codesample lang="ebuild"> +PATCHES=( + # Fix install location + "${FILESDIR}/${P}-destdir.patch" + # Respect MAKEOPTS #876543 + "${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> +</chapter> +</guide> diff --git a/ebuild-writing/functions/src_prepare/epatch/text.xml b/ebuild-writing/functions/src_prepare/epatch/text.xml deleted file mode 100644 index 4b0c427..0000000 --- a/ebuild-writing/functions/src_prepare/epatch/text.xml +++ /dev/null @@ -1,187 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_prepare/epatch/"> -<chapter> -<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>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> - -<p> -In its simplest form, <c>epatch</c> takes a single filename and -applies that patch. It will automatically <c>die</c> if the apply -fails. The following is taken from <c>app-misc/detox</c>: -</p> - -<codesample lang="ebuild"> -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 -<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_prepare() { - epatch "${WORKDIR}/${P}-suse-update.patch.bz2" - epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch" -} -</codesample> - -<p> -Remember to add the patch to <c>SRC_URI</c>. -</p> -</body> -</section> - -<section> -<title>Multiple Patches with <c>epatch</c></title> -<body> - -<p> -epatch can also apply multiple patches (which can be selectively based -upon arch) from a single directory. This can be useful if upstream -have releases that need more patches. -</p> - -<p> -A simple example: -</p> - -<codesample lang="ebuild"> -src_prepare() { - EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \ - EPATCH_FORCE="yes" epatch -} -</codesample> - -<p> -Here, one of the <c>SRC_URI</c> components is a tarball containing -many patches with file extension <c>.patch</c>. -</p> - -<p> -Variables which may be defined include: -</p> - -<table> - <tr> - <th>Variable</th> - <th>Purpose</th> - </tr> - <tr> - <ti><c>EPATCH_SOURCE</c></ti> - <ti>Specifies the directory in which epatch looks for patches.</ti> - </tr> - <tr> - <ti><c>EPATCH_SUFFIX</c></ti> - <ti>File extension for patches.</ti> - </tr> - <tr> - <ti><c>EPATCH_OPTS</c></ti> - <ti>Default options to <c>patch</c>.</ti> - </tr> - <tr> - <ti><c>EPATCH_EXCLUDE</c></ti> - <ti>List of patches to exclude.</ti> - </tr> - <tr> - <ti><c>EPATCH_FORCE</c></ti> - <ti> - Force epatch to apply patches even if they do not follow the - canonical naming form (set to <c>yes</c>). - </ti> - </tr> -</table> - -<p> -Bulk patches should be named in the form -<c>??_${ARCH}_foo.${EPATCH_SUFFIX}</c>. If they are -not, <c>EPATCH_FORCE="yes"</c> must be set. To apply a patch on <c>all</c> -archs, use all for the <c>${ARCH}</c> part. -</p> - -</body> -</section> -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_prepare/text.xml b/ebuild-writing/functions/src_prepare/text.xml index d62f2fd..342a112 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> @@ -83,7 +83,7 @@ src_prepare() { </section> <section> -<title><c>src_prepare</c> Processes</title> +<title><c>src_prepare</c> processes</title> <body> <p> The following subsections cover different topics which often occur @@ -95,6 +95,6 @@ when writing <c>src_prepare</c> functions. </section> </chapter> -<include href="epatch/"/> +<include href="eapply/"/> <include href="autopackage/"/> </guide> diff --git a/ebuild-writing/functions/src_test/text.xml b/ebuild-writing/functions/src_test/text.xml index baf0ad6..793e99f 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> @@ -51,7 +51,7 @@ src_test() { src_test() { cd "${S}"/src/testdir || die - # Test 49 won't work inside a portage environment + # 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 @@ -72,14 +72,22 @@ 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"/> +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> @@ -170,9 +178,17 @@ a more complete test suite. </p> <p> -Local server access within the build procedure is additionally -forbidden for the following reasons: +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 diff --git a/ebuild-writing/functions/src_unpack/other-formats/text.xml b/ebuild-writing/functions/src_unpack/other-formats/text.xml index 3647c80..891b322 100644 --- a/ebuild-writing/functions/src_unpack/other-formats/text.xml +++ b/ebuild-writing/functions/src_unpack/other-formats/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>Other archive formats</title> <body> <p> @@ -11,7 +11,7 @@ Instructions for some of them are detailed below: </body> <section> -<title>Zip Files</title> +<title>Zip files</title> <body> <p> @@ -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> @@ -27,7 +27,7 @@ If a package is supplied as a .zip file, you should: </section> <section> -<title>Shar Files</title> +<title>Shar files</title> <body> <p> If a package is supplied as a <c>.shar</c> file, you should repackage it locally @@ -39,7 +39,7 @@ done a release in at least ten years. </section> <section> -<title>RAR Files</title> +<title>RAR files</title> <body> <p> diff --git a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml index 4341944..0029c53 100644 --- a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml +++ b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>RPM sources</title> <body> <p> @@ -24,11 +24,11 @@ manner such as: </p> <codesample lang="ebuild"> -src_unpack () { +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> @@ -40,7 +40,7 @@ format. </body> <section> -<title>Example RPM Handling</title> +<title>Example RPM handling</title> <body> <p> @@ -55,16 +55,17 @@ patches. The filename should be <c>suse-fetchmail-6.2.5.54.1.ebuild</c>. # Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -EAPI="6" +EAPI=7 -inherit eapi7-ver rpm +inherit rpm MY_PV=$(ver_rs 3 '-') MY_P=fetchmail-${MY_PV} -SRC_URI="https://suse.osuosl.org/suse/i386/9.2/suse/src/${MY_P}.src.rpm" DESCRIPTION="SuSE 9.2 Fetchmail Source Package" 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" @@ -75,20 +76,18 @@ 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-$(ver_cut 1-3) - -src_unpack () { +src_unpack() { rpm_src_unpack ${A} } -src_prepare () { +src_prepare() { for i in "${WORKDIR}"/*.patch ; do eapply "${i}" done diff --git a/ebuild-writing/functions/src_unpack/text.xml b/ebuild-writing/functions/src_unpack/text.xml index 9c5f777..250d947 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> @@ -56,7 +56,7 @@ src_unpack() { </section> <section> -<title>Unpacking Tarballs</title> +<title>Unpacking tarballs</title> <body> <p> The <c>unpack</c> function should be used to unpack tarballs, compressed @@ -94,9 +94,6 @@ The <c>unpack</c> function recognizes the following file formats: <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> - <li><c>*.7z</c>, <c>*.7Z</c></li> - <li><c>*.rar</c>, <c>*.RAR</c></li> - <li><c>*.LHA</c>, <c>*.LHa</c>, <c>*.lha</c>, <c>*.lzh</c></li> </ul> <p> @@ -105,14 +102,14 @@ In EAPI 6 and later, filename extensions are matched case-insensitively. <important> Unless the utility needed for unpacking is in the system set, the ebuild must -specify the necessary build time dependency for it. +specify the necessary build time dependency (<c>BDEPEND</c>) for it. </important> </body> </section> <section> -<title><c>src_unpack</c> Actions</title> +<title><c>src_unpack</c> actions</title> <body> <p> The following subsections cover different topics which often occur when writing diff --git a/ebuild-writing/functions/src_unpack/vcs-sources/text.xml b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml index 46c8cd6..68fbe91 100644 --- a/ebuild-writing/functions/src_unpack/vcs-sources/text.xml +++ b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_unpack/vcs-sources/"> <chapter> -<title>Version Control System (VCS) Sources</title> +<title>Version Control System (VCS) sources</title> <body> <p> @@ -31,7 +31,7 @@ system for fetching. </body> <section> -<title>Disadvantages of VCS Sources</title> +<title>Disadvantages of VCS sources</title> <body> <p> @@ -71,7 +71,7 @@ $ git archive --prefix=emacs/ HEAD | xz > emacs-${PV}.tar.xz </section> <section> -<title>Disadvantages of VCS Live Sources</title> +<title>Disadvantages of VCS live sources</title> <body> <p> diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml index b15c0b1..c5a6cbc 100644 --- a/ebuild-writing/functions/text.xml +++ b/ebuild-writing/functions/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/"> <chapter> -<title>Ebuild Phase Functions</title> +<title>Ebuild phase functions</title> <body> <p> @@ -9,11 +9,17 @@ 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>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. +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> + +<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"/> @@ -54,12 +60,12 @@ 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/vcs-sources/#Disadvantages of VCS 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> diff --git a/ebuild-writing/messages/text.xml b/ebuild-writing/messages/text.xml index 85afa40..fe05e6b 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> @@ -28,7 +28,7 @@ occupy 4 columns with their fancy leading markers. </body> <section> -<title>Information Messages</title> +<title>Information messages</title> <body> <p> @@ -62,7 +62,7 @@ logged by default. <codesample lang="ebuild"> src_compile() { einfo "Starting a silent compile that takes hours." - ./build + ./build || die } </codesample> @@ -70,7 +70,7 @@ src_compile() { </section> <section> -<title>Warning Messages</title> +<title>Warning messages</title> <body> <p> @@ -82,7 +82,7 @@ used for warning messages rather than information. </section> <section> -<title>Error Messages</title> +<title>Error messages</title> <body> <p> @@ -119,7 +119,7 @@ See <uri link="::function-reference/message-functions/"/> for a full list of fun </section> <section> -<title>Good and Bad Messages</title> +<title>Good and bad messages</title> <body> <p> diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml index 6cf7609..4d549f4 100644 --- a/ebuild-writing/misc-files/metadata/text.xml +++ b/ebuild-writing/misc-files/metadata/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>Package and category <c>metadata.xml</c></title> <body> <p> @@ -114,7 +114,7 @@ metadata.xml: <ti> 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"> + <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> @@ -131,8 +131,9 @@ metadata.xml: <ti><c><slots></c></ti> <ti> This tag describes the - <uri link="::general-concepts/slotting">slots</uri> of a package. - It has two optional subtags: <slot> and <subslots>. + <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> @@ -172,17 +173,17 @@ metadata.xml: <ti><c><upstream></c></ti> <ti> This tag contains information about the upstream developers/project. - It supports multiple optional subtags: <maintainer>, - <changelog>, <doc>, <bugs-to>, - and <remote-id>. + 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><c><maintainer></c></ti> <ti> Provides information about the upstream maintainer. It requires a - <name> subtag to be specified, supports an optional - <email> subtag and an optional <c>status</c> attribute. + <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> @@ -217,7 +218,7 @@ metadata.xml: 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> @@ -272,9 +273,9 @@ There are also some attributes that can be used with these tags: 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="https://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> @@ -284,15 +285,12 @@ There are also some attributes that can be used with these tags: <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, other tags with or without the restrict attribute must be - present to cover all the versions of the package. A tag without - the restrict attribute serves as the default. 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>. + The restrict attribute allows one to restrict the application of certain + 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> @@ -301,12 +299,12 @@ There are also some attributes that can be used with these tags: <c><flag></c>, <c><slot></c> </ti> <ti> - When this attribute is required on the <flag> tag, it + When this attribute is required on the <c><flag></c> tag, it simply contains the name of the USE flag. For the - <slot> tag, it specifies the - <uri link="::general-concepts/slotting/#Slot Names"> + <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 <slot> tag to match all the slots of a + 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> @@ -320,7 +318,7 @@ There are also some attributes that can be used with these tags: 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 <maintainer> subtags of the <upstream> + for the <c><maintainer></c> subtags of the <c><upstream></c> element! </ti> </tr> @@ -344,8 +342,7 @@ There are also some attributes that can be used with these tags: 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>. + <uri link="::general-concepts/projects/">Gentoo project</uri>. </ti> </tr> @@ -354,7 +351,7 @@ There are also some attributes that can be used with these tags: </body> </section> <section> -<title>Package Metadata</title> +<title>Package metadata</title> <body> <p> All packages <b>must</b> include a <c>metadata.xml</c> file which @@ -371,7 +368,7 @@ using the <c>app-portage/metagen</c> tool. </p> <p> -Commits of package metadata files are handled by <c>repoman</c> as +Commits of package metadata files are handled by <c>pkgdev</c> as part of regular package maintenance. </p> @@ -384,7 +381,7 @@ GLEP 67</uri>. </body> <subsection> -<title>Package Metadata Examples</title> +<title>Package metadata examples</title> <body> <p> @@ -396,7 +393,7 @@ these files verbatim and should be taken as hypothetical examples. </body> <subsubsection> -<title>Projects as Maintainers</title> +<title>Projects as maintainers</title> <body> <p> @@ -405,13 +402,13 @@ 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 <name> subtag. It also provides a long package +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"> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> <maintainer type="project"> <email>office@gentoo.org</email> @@ -461,7 +458,7 @@ projects listing</uri> available on the Gentoo Wiki: </body> </subsubsection> <subsubsection> -<title>Local USE Flag Descriptions</title> +<title>Local USE flag descriptions</title> <body> <p> @@ -470,20 +467,15 @@ The second example is formed after the <c>metadata.xml</c> of 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 <bugs-to> tag due to the presence of an email address +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 -<email> tags require no such prefix. +<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"> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> - <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> <maintainer type="person"> <email>larry@gentoo.org</email> <name>Larry the Cow</name> @@ -493,7 +485,7 @@ as opposed to a URL. Conversely, email addresses specified in the </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="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> @@ -502,13 +494,18 @@ as opposed to a URL. Conversely, email addresses specified in the 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> </subsubsection> <subsubsection> -<title>Split Maintainership</title> +<title>Split maintainership</title> <body> <p> @@ -524,9 +521,9 @@ project. Note the use of "&gt;" as opposed to ">" in <p> The example also uses the <c><pkg></c> tag in USE flag descriptions. Slot dependency specifiers are not allowed inside -<pkg>, therefore the notation -<pkg>sys-boot/grub</pkg><c>:2</c> is adopted as opposed to -<pkg>sys-boot/grub<c>:2</c></pkg>. +<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> @@ -536,7 +533,7 @@ is demonstrated. <codesample lang="sgml"> <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> <maintainer restrict="&gt;=sys-boot/grub-2" type="person"> <email>floppym@gentoo.org</email> @@ -577,7 +574,7 @@ is demonstrated. </body> </subsubsection> <subsubsection> -<title>Slots and Subslots</title> +<title>Slots and subslots</title> <body> <p> @@ -595,7 +592,7 @@ specified in the <c><subslots></c> tag. <codesample lang="sgml"> <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> <maintainer type="project"> <email>base-system@gentoo.org</email> @@ -628,16 +625,16 @@ specified in the <c><subslots></c> tag. </subsubsection> </subsection> <subsection> -<title>Maintainer-Needed</title> +<title>Maintainer-needed</title> <body> <p> -Maintainer-needed, or orphaned, packages have no maintainers -responsible for them. Per +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 <maintainer> -subtags under <pkgmetadata> in their <c>metadata.xml</c>. A strict test -for this condition would be: +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> <pre> @@ -656,7 +653,7 @@ part of the QA reports. <codesample lang="sgml"> <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> <!-- maintainer-needed --> <upstream> @@ -682,7 +679,7 @@ part of the QA reports. </section> <section> -<title>Category Metadata</title> +<title>Category metadata</title> <body> <p> For categories, <c>metadata.xml</c> specifies a long description (in @@ -691,7 +688,7 @@ English and optionally in other languages). A typical example: <codesample lang="sgml"> <?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<!DOCTYPE catmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <catmetadata> <longdescription lang="en"> The app-vim category contains plugins and syntax file diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml index 91afd33..862910c 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> @@ -25,12 +25,14 @@ number in the patch name as a suffix to the version part <d/> <p> Larger patches should be -<uri link="::general-concepts/mirrors/#Suitable Download Hosts"> +<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>. +<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> @@ -38,7 +40,7 @@ Patches included in <c>${FILESDIR}</c> should never be compressed. </note> <warning> -Starting from EAPI=6 a strip patch level was limited to the <c>-p1</c>. +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. @@ -52,7 +54,7 @@ up the tree too much. </body> <section> -<title>Patch Descriptions</title> +<title>Patch descriptions</title> <body> <p> It is possible to include a description with a patch. This is often @@ -66,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 VCS 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. @@ -94,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 @@ -111,7 +113,66 @@ from the <c>vim</c> patch tarball: </section> <section> -<title>Clean Patch Howto</title> +<title>Conditional patching</title> +<body> + +<p> +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> @@ -138,7 +199,7 @@ assess a patch without searching through many other files. </subsection> <subsection> -<title>File Naming</title> +<title>File naming</title> <body> <p> @@ -292,6 +353,14 @@ files automatically. Alternatively, you can specify the <c>-E</c> option with </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> diff --git a/ebuild-writing/misc-files/text.xml b/ebuild-writing/misc-files/text.xml index 416070b..3fe6026 100644 --- a/ebuild-writing/misc-files/text.xml +++ b/ebuild-writing/misc-files/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/misc-files/"> <chapter> -<title>Miscellaneous Files</title> +<title>Miscellaneous files</title> <body> <p> diff --git a/ebuild-writing/text.xml b/ebuild-writing/text.xml index 9420045..0817a04 100644 --- a/ebuild-writing/text.xml +++ b/ebuild-writing/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/"> <chapter> -<title>Ebuild Writing</title> +<title>Ebuild writing</title> <body> <p> diff --git a/ebuild-writing/use-conditional-code/text.xml b/ebuild-writing/use-conditional-code/text.xml index b949fc0..cb818a2 100644 --- a/ebuild-writing/use-conditional-code/text.xml +++ b/ebuild-writing/use-conditional-code/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>USE flag conditional code</title> <body> <p> @@ -15,20 +15,20 @@ 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. 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. +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> <c>die</c> will not work as expected within a subshell, so code in the form <c>use foo && ( blah ; blah )</c> should be avoided in favour of a proper if -statement. See <uri link="::ebuild-writing/error-handling/#die and Subshells"/>. +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} + rm -fr "${vimfiles}"/{compiler,doc,ftplugin,indent} || die fi # Inverse USE conditional blocks... @@ -39,11 +39,11 @@ statement. See <uri link="::ebuild-writing/error-handling/#die and Subshells"/>. fi # USE conditional statements... - use ssl && epatch "${FILESDIR}/${P}-ssl.patch" + 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" + 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 index b97af10..9e2bc1c 100644 --- a/ebuild-writing/user-submitted/text.xml +++ b/ebuild-writing/user-submitted/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/user-submitted/"> <chapter> -<title>User-submitted Ebuilds</title> +<title>User-submitted ebuilds</title> <body> @@ -24,19 +24,27 @@ The user-submitted ebuild must not contain custom headers like this: 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"> +<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. +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</c> command +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. diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml index 9b2b49d..679d028 100644 --- a/ebuild-writing/users-and-groups/text.xml +++ b/ebuild-writing/users-and-groups/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/users-and-groups/"> <chapter> -<title>Users and Groups</title> +<title>Users and groups</title> <body> <p> @@ -14,12 +14,12 @@ categories. <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 499. 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 499 downwards. 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. +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> diff --git a/ebuild-writing/using-eclasses/text.xml b/ebuild-writing/using-eclasses/text.xml index 943e92d..7fa2c7b 100644 --- a/ebuild-writing/using-eclasses/text.xml +++ b/ebuild-writing/using-eclasses/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/using-eclasses/"> <chapter> -<title>Using Eclasses</title> +<title>Using eclasses</title> <body> <p> @@ -14,15 +14,24 @@ how to use an eclass which has already been written. </body> <section> -<title>The <c>inherit</c> Function</title> +<title>The <c>inherit</c> function</title> <body> <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> +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> diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml index b6cebb3..97e5995 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> @@ -12,7 +12,7 @@ which are of use throughout the ebuild. </body> <section> -<title>Predefined Read-Only Variables</title> +<title>Predefined read-only variables</title> <body> <p> @@ -64,9 +64,8 @@ for these variables when writing ebuilds. <tr> <ti><c>FILESDIR</c></ti> <ti> - Path to the ebuild's <c>files/</c> directory, commonly used - for small patches and files. For example: - <c>"${PORTDIR}/${CATEGORY}/${PN}/files"</c>. + Path to the package's <c>files/</c> directory, commonly used for small + patches and other files. </ti> </tr> <tr> @@ -102,8 +101,8 @@ for these variables when writing ebuilds. <ti><c>ROOT</c></ti> <ti> 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"/> + merged. Only allowed in pkg_* phases. + See <uri link="::ebuild-writing/variables/#ROOT"/> </ti> </tr> <tr> @@ -185,10 +184,61 @@ for these variables when writing ebuilds. </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> -<title>Ebuild-defined Variables</title> +<title>Ebuild-defined variables</title> <body> <p> @@ -203,7 +253,7 @@ 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> @@ -231,7 +281,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> @@ -239,20 +289,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> @@ -260,8 +310,8 @@ 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> @@ -276,13 +326,13 @@ The following variables may or must be defined by every ebuild. <ti><c>PROPERTIES</c></ti> <ti> A space-delimited list of properties, with conditional syntax support. - <c>interactive</c> is the only valid value for now. + <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> @@ -290,31 +340,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"/>. + (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> @@ -348,45 +398,12 @@ The following variables may or must be defined by every ebuild. </table> </body> -</section> - -<section> -<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. -</p> - -</body> -</section> - -<section> -<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> -</section> -<section> +<subsection> <title>SRC_URI</title> -<subsection> -<title>Conditional Sources</title> +<subsubsection> +<title>Conditional sources</title> <body> <p> @@ -404,10 +421,10 @@ SRC_URI="https://example.com/files/${P}-core.tar.bz2 </codesample> </body> -</subsection> +</subsubsection> -<subsection> -<title>Renaming Sources</title> +<subsubsection> +<title>Renaming sources</title> <body> <p> @@ -429,10 +446,9 @@ SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz" </codesample> </body> -</subsection> +</subsubsection> - -<subsection> +<subsubsection> <title>Third-party mirrors</title> <body> @@ -481,36 +497,76 @@ There are two valid cases for using <c>thirdpartymirrors</c>: <p> In any other case, the primary location must be used instead. The distfiles -will be <uri link="::general-concepts/mirrors">mirrored onto Gentoo +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> -</subsection> -</section> +</subsubsection> -<section> -<title>IUSE</title> +<subsubsection> +<title>Lifting restrictions</title> <body> <p> -Note that the <c>IUSE</c> variable is cumulative, so there is no need to specify -USE flags used only within inherited eclasses within the ebuild's IUSE. +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> -<note> -You need not assign the IUSE variable in your ebuild if it is empty. -</note> + +<codesample lang="ebuild"> +EAPI="8" + +SRC_URI="${P}.tar.gz + mirror+https://dev.gentoo.org/~larry/distfiles/${P}-addons.tar.gz" + +RESTRICT="fetch" +</codesample> <p> -Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x64-macos</c> and so on) should -not be listed. +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> -</section> +</subsubsection> +</subsection> -<section> +<subsection> <title>LICENSE</title> <body> @@ -522,61 +578,185 @@ GLEP 23</uri> for details. </p> </body> -</section> +</subsection> -<section> -<title>ROOT</title> +<subsection> +<title>SLOT</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>. +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> -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>. +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> -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>. +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> -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. +See <uri link="::keywording/"/> for how to handle this variable. </p> +</body> +</subsection> + +<subsection> +<title>IUSE</title> +<body> + <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: +Note that the <c>IUSE</c> variable is cumulative, so there is no need to specify +USE flags used only within inherited eclasses within the ebuild's IUSE. +</p> +<note> +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>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"> -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 -} +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>Variables reserved for the package manager</title> +<body> + +<p> +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> <section> -<title>Version and Name Formatting Issues</title> +<title>Version and name formatting issues</title> <body> <p> @@ -594,6 +774,7 @@ you know what you are doing, is to use these functions: <codesample lang="ebuild"> inherit eapi7-ver + MY_PN="Foo" # Replace the second period separator in PV with - MY_PV=$(ver_rs 2 '-') @@ -612,10 +793,11 @@ 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 -eapi7-ver 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> @@ -664,11 +846,18 @@ follows. </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> +<title>Trailing slashes in variables</title> <body> <p> @@ -739,72 +928,167 @@ have no direct correlation with the expected string should be avoided. </section> <section> -<title>REQUIRED_USE</title> +<title>User environment</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": +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> -<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> +<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> -<subsection> -<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": +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> -<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> + +<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> -</subsection> </section> - </chapter> </guide> diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml index 70f9fff..8c4c910 100644 --- a/eclass-writing/text.xml +++ b/eclass-writing/text.xml @@ -1,21 +1,22 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="eclass-writing/"> <chapter> -<title>Eclass Writing Guide</title> - +<title>Eclass writing guide</title> <body> + <p> 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> +<title>Purpose of eclasses</title> <body> <p> @@ -28,7 +29,7 @@ Roughly speaking, there are three kinds of eclass: <li> Those which provide common functions which are used by many ebuilds (for example, <c>autotools</c>, <c>bash-completion-r1</c>, <c>flag-o-matic</c>, - <c>toolchain-funcs</c> + <c>toolchain-funcs</c>) </li> <li> Those which provide a basic build system for many similar packages (for @@ -44,7 +45,7 @@ Roughly speaking, there are three kinds of eclass: </section> <section> -<title>Adding and Updating Eclasses</title> +<title>Adding and updating eclasses</title> <body> <p> @@ -63,6 +64,12 @@ and end up breaking something, expect to be in a lot of trouble. </p> <p> +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> 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. @@ -70,7 +77,10 @@ package, and thus does not typically require changes to be emailed for review. <p> When removing a function or changing the API of an eclass, make sure that -it doesn't break any ebuilds in the Gentoo repository. +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> @@ -79,23 +89,34 @@ If there is an existing maintainer for an eclass (this is usually the case), you </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> <section> -<title>Removing Eclasses</title> +<title>Removing eclasses</title> <body> -<p>No longer used eclasses may be removed from the tree, but developers must -adhere to the following process:</p> +<p> +Eclasses that are no longer in use may be removed from the tree, but developers +must adhere to the following process: +</p> <ol> <li> @@ -116,12 +137,17 @@ adhere to the following process:</p> </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 at +least 30 days before removing the eclass. +</note> </body> </section> <section> -<title>Documenting Eclasses</title> +<title>Documenting eclasses</title> <body> <p> @@ -132,16 +158,31 @@ each block documents an individual element of an eclass. <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. +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> <section> -<title>Basic Eclass Format</title> +<title>Basic eclass format</title> <body> <p> @@ -162,133 +203,107 @@ summarizes the available documentation tags: <table> <tr> <th>tag</th> - <th>optional?</th> + <th>required?</th> <th>arguments</th> <th>description</th> </tr> <tr> - <ti> - <c>@ECLASS:</c> - </ti> - <ti> - NO - </ti> - <ti> - Name of the eclass being documented. - </ti> + <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> - NO - </ti> - <ti> - One or more name and email pairs. - </ti> + <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> - YES - </ti> - <ti> - One or more name and email pairs. - </ti> + <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> - YES - </ti> - <ti> - Multiline freetext. - </ti> - <ti> - Describes how bugs related to this eclass should be reported. - </ti> + <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> - YES - </ti> - <ti> - A URI string. - </ti> - <ti> - Points to the URL of the VCS that contains the eclass source. - </ti> + <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> - <c>@BLURB:</c> - </ti> - <ti> - NO - </ti> - <ti> - Single line freetext. + 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>@DESCRIPTION:</c> - </ti> - <ti> - YES - </ti> - <ti> - Multiline freetext. - </ti> - <ti> - Long description for the eclass. - </ti> + <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>@DEAD</c></ti> + <ti>No</ti> + <ti><d/></ti> <ti> - <c>@EXAMPLE:</c> - </ti> - <ti> - YES - </ti> - <ti> - Multiline freetext. - </ti> - <ti> - Examples that illustrate various uses of this eclass. + For an eclass that is slated for removal; prevents the eclass-manpages + package from documenting the eclass. </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> <section> -<title>Eclass Variables</title> +<title>Eclass variables</title> <body> <p> @@ -306,20 +321,14 @@ variables are as follows: <table> <tr> <th>tag</th> - <th>optional?</th> + <th>required?</th> <th>arguments</th> <th>description</th> </tr> <tr> - <ti nowrap="nowrap"> - <c>@ECLASS-VARIABLE:</c> - </ti> - <ti> - NO - </ti> - <ti> - Name of the eclass variable to which the documentation applies. - </ti> + <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 @@ -328,61 +337,66 @@ variables are as follows: </ti> </tr> <tr> + <ti><c>@PRE_INHERIT</c></ti> + <ti>No</ti> + <ti><d/></ti> <ti> - <c>@DEFAULT_UNSET</c> + 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> - YES + 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> - <d/> + 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. + developer </ti> </tr> <tr> - <ti> - <c>@INTERNAL</c> - </ti> - <ti> - YES - </ti> - <ti> - <d/> - </ti> - <ti> - Indicates that the variable is internal to the eclass. - </ti> + <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> - YES - </ti> - <ti> - <d/> - </ti> - <ti> - Indicates that this variable must be set by the developer. - </ti> + <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>@DESCRIPTION:</c> - </ti> - <ti> - NO - </ti> - <ti> - Multiline freetext. - </ti> - <ti> - Long description for the eclass variable. - </ti> + <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> @@ -390,7 +404,7 @@ variables are as follows: </section> <section> -<title>Eclass Functions</title> +<title>Eclass functions</title> <body> <p> @@ -407,35 +421,23 @@ documentation are: <table> <tr> <th>tag</th> - <th>optional?</th> + <th>required?</th> <th>arguments</th> <th>description</th> </tr> <tr> - <ti> - <c>@FUNCTION:</c> - </ti> - <ti> - NO - </ti> - <ti> - Name of the function to which the documentation block applies. - </ti> + <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. + 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><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> @@ -443,63 +445,45 @@ documentation are: </ti> </tr> <tr> - <ti> - <c>@RETURN:</c> - </ti> - <ti> - <b>*</b> - </ti> - <ti> - Return value of the function. - </ti> + <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>: Not optional for functions that return a value.</p> + <p><b>*</b>: Required for functions that return a value.</p> </ti> </tr> <tr> - <ti> - <c>@MAINTAINER:</c> - </ti> - <ti> - YES - </ti> - <ti> - Multiline freetext. - </ti> + <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> - YES - </ti> - <ti> - <d/> - </ti> + <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. + not be called from outside </ti> </tr> <tr> - <ti> - <c>@DESCRIPTION:</c> - </ti> - <ti> - <b>*</b> - </ti> - <ti> - Multiline freetext. - </ti> + <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> Not optional if <c>RETURN:</c> is absent.</p> + <p><b>*:</b> Required if <c>RETURN:</c> is absent.</p> </ti> </tr> </table> @@ -507,7 +491,7 @@ documentation are: </body> </section> <section> -<title>Eclass Function Variables</title> +<title>Eclass function variables</title> <body> <p> @@ -519,19 +503,15 @@ using the following tags: <table> <tr> <th>tag</th> - <th>optional?</th> + <th>required?</th> <th>arguments</th> <th>description</th> </tr> <tr> + <ti><c>@VARIABLE:</c></ti> + <ti>Yes</ti> <ti> - <c>@VARIABLE:</c> - </ti> - <ti> - NO - </ti> - <ti> - Name of the function-specific variable to which the documentation applies. + Name of the function-specific variable to which the documentation applies </ti> <ti> This tag applies to variables consumed by specific functions of @@ -540,61 +520,47 @@ using the following tags: </ti> </tr> <tr> - <ti> - <c>@DEFAULT_UNSET</c> - </ti> - <ti> - YES - </ti> - <ti> - <d/> - </ti> + <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. + developer </ti> </tr> <tr> - <ti> - <c>@INTERNAL</c> - </ti> - <ti> - YES - </ti> - <ti> - <d/> - </ti> - <ti> - Indicates that the variable is internal to the eclass function. - </ti> + <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> - YES - </ti> - <ti> - <d/> - </ti> - <ti> - Indicates that this variable must be set by the developer. - </ti> + <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>@DESCRIPTION:</c> - </ti> - <ti> - NO - </ti> - <ti> - Multiline freetext. - </ti> - <ti> - Long description for the function variable. - </ti> + <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> @@ -602,7 +568,7 @@ using the following tags: </section> <section> -<title>Simple Common Functions Eclass Example</title> +<title>Simple common functions eclass example</title> <body> <p> @@ -623,14 +589,14 @@ a single function, <c>domacosapp</c>. # @FUNCTION: domacosapp # @USAGE: <app-file> [new-file] # @DESCRIPTION: -# Install the given .app file into the appropriate location. If +# 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. +# 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}" + newins "$1" "${2:-${1}}" fi } </codesample> @@ -639,15 +605,15 @@ domacosapp() { </section> <section> -<title>Export Functions</title> +<title>Export functions</title> <body> <p> 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 +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> @@ -664,11 +630,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 } + +EXPORT_FUNCTIONS src_compile </codesample> <p> @@ -676,7 +642,7 @@ Then an ebuild could do this: </p> <codesample lang="ebuild"> -inherit fnord.eclass +inherit fnord src_compile() { do_pre_stuff || die @@ -685,21 +651,131 @@ src_compile() { } </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-2021 Gentoo Authors +if [[ -z ${_FOO_ECLASS} ]]; then +_FOO_ECLASS=1 + +# Variables and functions go here + +fi +</codesample> + +<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> + +<codesample lang="ebuild"> +if [[ -z ${_FOO_ECLASS} ]]; then +_FOO_ECLASS=1 + +foo_src_compile() { + ... +} +fi + +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> + +<section> +<title>Handling incorrect usage of an eclass</title> +<body> + +<p> +Sometimes an eclass is used incorrectly by an ebuild and the eclass +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. +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-2022 Gentoo Authors +# Distributed under the terms of the GNU General Public License v2 + +# @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} 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 @@ -710,70 +786,60 @@ something like the following: # @BLURB: Demonstrate a simple build system eclass. # @DESCRIPTION: # Demonstrates EXPORT_FUNCTIONS and defines simple wrappers for the -# (hypothetical) jmake build system and a default src_compile. +# (hypothetical) jmake build system along with default src_configure and +# src_compile phase functions. -EXPORT_FUNCTIONS src_compile +case ${EAPI} in + 7|8) ;; + *) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;; +esac + +if [[ -z ${_JMAKE_ECLASS} ]]; then +_JMAKE_ECLASS=1 -DEPEND=">=sys-devel/jmake-2" +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() { jmake configure --prefix=/usr "$@" } -# @FUNCTION: jmake-build +# @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_build() { jmake dep && jmake build "$@" } -# @FUNCTION: jmake-src_compile +# @FUNCTION: jmake_src_compile # @DESCRIPTION: -# Calls jmake-configure() and jmake-build() to compile a jmake project. +# Calls jmake_build() to compile a jmake project. jmake_src_compile() { - jmake-configure || die "configure failed" - jmake-build || die "build failed" + jmake_build || die "build failed" } -</codesample> -</body> -</section> +fi -<section> -<title>Handling incorrect usage of an eclass</title> -<body> - -<p> -Sometimes an eclass is used incorrectly by an ebuild and the eclass -knows it is being used incorrectly- 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. -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-2021 Gentoo Authors -# Distributed under the terms of the GNU General Public License v2 - -# @ECLASS: eapi-die.eclass -# @MAINTAINER: -# Gentoo Devmanual Project <devmanual@gentoo.org> -# @BLURB: Calls die when used with an invalid EAPI. - -case ${EAPI:-0} in - 0) die "this eclass doesn't support EAPI 0" ;; - *) ;; -esac +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 646c75e..5e7b28d 100644 --- a/function-reference/build-functions/text.xml +++ b/function-reference/build-functions/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/build-functions/"> <chapter> -<title>Build Functions Reference</title> +<title>Build functions reference</title> <body> @@ -34,7 +34,7 @@ during the unpack and compile stages. <ti> 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"/> + See <uri link="::ebuild-writing/functions/src_configure/configuring/#econf options"/> for details. </ti> </tr> diff --git a/function-reference/error-functions/text.xml b/function-reference/error-functions/text.xml index 70153eb..f3a542b 100644 --- a/function-reference/error-functions/text.xml +++ b/function-reference/error-functions/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/error-functions/"> <chapter> -<title>Error Functions Reference</title> +<title>Error functions reference</title> <body> <p> diff --git a/function-reference/install-functions/text.xml b/function-reference/install-functions/text.xml index da2af83..a221527 100644 --- a/function-reference/install-functions/text.xml +++ b/function-reference/install-functions/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/install-functions/"> <chapter> -<title>Install Functions Reference</title> +<title>Install functions reference</title> <body> <p> @@ -103,9 +103,10 @@ The <c>*into</c> functions create the directory if it does not already exist. <c>dobin</c> </ti> <ti> - Install a binary into <c>/usr/bin</c>, set the file mode to 0755 - and set the ownership to superuser or its equivalent on the - system or installation at hand. + 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> @@ -277,11 +278,16 @@ The <c>*into</c> functions create the directory if it does not already exist. <c>dosym</c> </ti> <ti> - Create a symlink to the target specified as the first parameter, - at the path specified by the second parameter. Note that - the target is interpreted <e>verbatim</e>; it needs to either - specify a relative path or an absolute path including - <c>${EPREFIX}</c>. + <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> @@ -426,10 +432,11 @@ The <c>*into</c> functions create the directory if it does not already exist. <c>dostrip</c> </ti> <ti> - Introduced with EAPI=7, controls the stripping of executables. - Normally executed to exclude from stripping. - Eg. <c>dostrip -x /path/to/important.so</c>. May also be used to include binaries - to strip when <c>RESTRICT=strip</c> without the -x option. + 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 af6771a..cde7eb6 100644 --- a/function-reference/message-functions/text.xml +++ b/function-reference/message-functions/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/message-functions/"> <chapter> -<title>Message Functions Reference</title> +<title>Message functions reference</title> <body> <p> @@ -86,7 +86,7 @@ displaying informational messages. </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 da24380..529bb77 100644 --- a/function-reference/query-functions/text.xml +++ b/function-reference/query-functions/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/query-functions/"> <chapter> -<title>Query Functions Reference</title> +<title>Query functions reference</title> <body> <p> @@ -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,6 +77,15 @@ query variables and similar state. </tr> <tr> <ti> + <c>in_iuse flag</c> + </ti> + <ti> + 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> @@ -110,9 +131,8 @@ query variables and similar state. </ti> <ti> True if <c>pkg</c> (can include - <uri link="::general-concepts/dependencies#version specifiers"/> - and - <uri link="::general-concepts/dependencies#built with use dependencies"/>) + <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. diff --git a/function-reference/sandbox-functions/text.xml b/function-reference/sandbox-functions/text.xml index 4f355c5..fa68d07 100644 --- a/function-reference/sandbox-functions/text.xml +++ b/function-reference/sandbox-functions/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/sandbox-functions/"> <chapter> -<title>Sandbox Functions Reference</title> +<title>Sandbox functions reference</title> <body> <p> @@ -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 2b90dfc..d8e844f 100644 --- a/function-reference/text.xml +++ b/function-reference/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="function-reference/"> <chapter> -<title>Function Reference</title> +<title>Function reference</title> <body> <p> diff --git a/general-concepts/autotools/text.xml b/general-concepts/autotools/text.xml index b7170ba..39edb19 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> +<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> @@ -32,7 +33,7 @@ when working with ebuilds: </body> <section> -<title>Major Autotools Components</title> +<title>Major Autotools components</title> <body> <p> @@ -107,7 +108,7 @@ instead. </section> <section> -<title>Simple Autotools Patching Example</title> +<title>Simple Autotools patching example</title> <body> <p> @@ -116,38 +117,36 @@ 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() { + 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 + eautoreconf } -src_compile() { +src_configure() { econf $(use_enable nls) - emake } </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> <section> -<title>The <c>configure.ac</c> File</title> +<title>The <c>configure.ac</c> file</title> <body> <p> @@ -160,7 +159,7 @@ These macros can check for packages and libraries, handle <c>--enable</c> and </body> <subsection> -<title>Basic Format of <c>configure.ac</c></title> +<title>Basic format of <c>configure.ac</c></title> <body> <p> @@ -290,7 +289,7 @@ These are used to make the <c>./configure</c> script generate the relevant files </subsection> <subsection> -<title>Enable and Disable Checks</title> +<title>Enable and disable checks</title> <body> <p> @@ -347,7 +346,7 @@ misunderstanding of the <c>AC_ARG_ENABLE</c> arguments is to blame. </subsection> <subsection> -<title>With and Without Checks</title> +<title>With and without checks</title> <body> <p> @@ -372,7 +371,7 @@ and there are standard macros which include <c>with</c> options. </subsection> <subsection> -<title>Automatic Checks</title> +<title>Automatic checks</title> <body> <p> @@ -391,7 +390,7 @@ whether or not to enable a feature. If you find a package which does this, you </subsection> <subsection> -<title>Quoting Rules for <c>configure.ac</c></title> +<title>Quoting rules for <c>configure.ac</c></title> <body> <p> @@ -440,7 +439,7 @@ rather than leaving things unquoted. </section> <section> -<title>The <c>Makefile.am</c> Files</title> +<title>The <c>Makefile.am</c> files</title> <body> <p> @@ -491,16 +490,16 @@ This is handled via the macro <c>AC_SUBST(VARNAME)</c> in <c>configure.ac</c>. </body> <subsection> -<title>Makefile Variables</title> +<title>Makefile variables</title> <body> <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> @@ -528,7 +527,7 @@ Remember to manually run <c>autoconf</c> then <c>automake</c> if you do this. </section> <section> -<title>The <c>config.h.in</c> File</title> +<title>The <c>config.h.in</c> file</title> <body> <p> @@ -542,7 +541,7 @@ version. </section> <section> -<title><c>aclocal</c> and <c>m4</c> Files</title> +<title><c>aclocal</c> and <c>m4</c> files</title> <body> <p> @@ -591,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> @@ -602,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> @@ -633,7 +646,7 @@ know almost nothing about... Yay! </section> <section> -<title>Further Autotools Reading</title> +<title>Further autotools reading</title> <body> <p> diff --git a/general-concepts/config-protect/text.xml b/general-concepts/config-protect/text.xml index ec74a86..1d598a3 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> - +<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..5fb9d19 --- /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/dependencies/text.xml b/general-concepts/dependencies/text.xml index 319137f..3201d91 100644 --- a/general-concepts/dependencies/text.xml +++ b/general-concepts/dependencies/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/dependencies/"> <chapter> <title>Dependencies</title> @@ -9,6 +9,20 @@ 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> @@ -20,15 +34,15 @@ provided by <c>emerge</c>. <p> In order to avoid ambiguity, we use the following terms to indicate different -systems when cross-compiling: +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. When - cross-compiling, they are not installed into the system being built. + to the CBUILD system can be executed during build time. </dd> <dt>CHOST</dt> @@ -39,21 +53,28 @@ systems when cross-compiling: </dl> <p> -When not cross-compiling, CBUILD and CHOST have the same value and both classes -of dependencies are merged. +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> +<title>Build dependencies</title> <body> <p> 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 +<uri link="::general-concepts/dependencies/#Implicit system dependency"/> for exemptions). </p> @@ -73,7 +94,7 @@ In earlier EAPIs, all build dependencies are placed in <c>DEPEND</c>. </subsection> <subsection> -<title>Runtime Dependencies</title> +<title>Runtime dependencies</title> <body> <p> @@ -97,7 +118,7 @@ Items which are in <c>RDEPEND</c> but not <c>DEPEND</c> could <e>in theory</e> b </subsection> <subsection> -<title>Post Dependencies</title> +<title>Post dependencies</title> <body> <p> @@ -112,10 +133,10 @@ while in general case <c>RDEPEND</c> should be used instead. </section> <section> -<title>Dependency Syntax</title> +<title>Dependency syntax</title> <subsection> -<title>Basic Dependency Syntax</title> +<title>Basic dependency syntax</title> <body> <p> @@ -139,7 +160,7 @@ When specifying names, the category part should be treated as mandatory. </subsection> <subsection> -<title>Version Dependencies</title> +<title>Version dependencies</title> <body> <p> @@ -157,7 +178,7 @@ This states that at least version 0.9.7d of <c>openssl</c> is required. </body> <subsubsection> -<title>Version Specifiers</title> +<title>Version specifiers</title> <body> <p> @@ -202,7 +223,7 @@ Available version specifiers are: </subsubsection> <subsubsection> -<title>Ranged Dependencies</title> +<title>Ranged dependencies</title> <body> <p> @@ -291,6 +312,12 @@ 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. @@ -314,7 +341,7 @@ 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> @@ -324,7 +351,7 @@ newer package that caused the issues. </subsection> <subsection> -<title>SLOT Dependencies</title> +<title>SLOT dependencies</title> <body> <p> @@ -333,7 +360,7 @@ the package name, where 'SLOT' is the <c>SLOT</c> of the package wanted: </p> <codesample lang="ebuild"> -DEPEND="qt3? ( x11-libs/qt:3 ) +DEPEND="qt5? ( dev-qt/qtcore:5 ) gtk? ( x11-libs/gtk+:2 ) </codesample> @@ -342,36 +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 ) +DEPEND="qt5? ( ~dev-qt/qtcore-5.15.2:5 ) gtk? ( >=x11-libs/gtk+-2.24.9:2 ) </codesample> </body> <subsubsection> -<title>Slot Operators</title> +<title>Slot operators</title> <body> <p> 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> @@ -383,12 +421,44 @@ RDEPEND="media-libs/cogl:1.0= gnutls? ( >=net-libs/gnutls-2.8:= )" </codesample> +<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> </subsubsection> </subsection> <subsection> -<title>USE-Conditional Dependencies</title> +<title>USE-conditional dependencies</title> <body> <p> @@ -423,7 +493,9 @@ This can be nested: <codesample lang="ebuild"> DEPEND="!build? ( + >=sys-libs/ncurses-5.2-r2 gcj? ( + >=media-libs/libart_lgpl-2.1 gtk? ( x11-libs/libXt x11-libs/libX11 @@ -433,9 +505,7 @@ DEPEND="!build? ( >=x11-libs/gtk+-2.2 x11-libs/pango ) - >=media-libs/libart_lgpl-2.1 ) - >=sys-libs/ncurses-5.2-r2 nls? ( sys-devel/gettext ) )" </codesample> @@ -444,9 +514,15 @@ DEPEND="!build? ( </subsection> <subsection> -<title>Any of Many Dependencies</title> +<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> @@ -465,7 +541,7 @@ DEPEND="baz? ( || ( app-misc/foo app-misc/bar ) )" </body> <subsubsection> -<title>Any of Many Versus USE</title> +<title>Any of many versus USE</title> <body> <p> @@ -490,7 +566,7 @@ flag is not necessary if and only if all of the following hold: </subsection> <subsection> -<title>Built with USE Dependencies</title> +<title>Built with USE dependencies</title> <body> <p> @@ -574,7 +650,7 @@ DEPEND=" </section> <section> -<title>Tips for Checking Dependencies</title> +<title>Tips for checking dependencies</title> <body> <p> @@ -587,7 +663,9 @@ package: <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 + 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> @@ -603,21 +681,28 @@ package: <dt>Look at the application/library website</dt> <dd> Check the application website for possible dependencies that they suggest - are needed + 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 + packages. </dd> <dt> Remember non-binary dependencies such as pkg-config, doc generation - programs, etc. + 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. + 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> @@ -625,7 +710,7 @@ package: </section> <section> -<title>Implicit System Dependency</title> +<title>Implicit system dependency</title> <body> <p> @@ -653,7 +738,7 @@ tarball. </section> <section> -<title>Test Dependencies</title> +<title>Test dependencies</title> <body> <p> @@ -691,7 +776,7 @@ DEPEND="test? ( dev-util/foo )" </section> <section> -<title>Circular Dependencies</title> +<title>Circular dependencies</title> <body> <p> @@ -738,5 +823,22 @@ There are three kinds of circular dependencies: </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/ebuild-revisions/text.xml b/general-concepts/ebuild-revisions/text.xml index c370d27..2c8531a 100644 --- a/general-concepts/ebuild-revisions/text.xml +++ b/general-concepts/ebuild-revisions/text.xml @@ -1,14 +1,14 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/ebuild-revisions/"> <chapter> -<title>Ebuild Revisions</title> +<title>Ebuild revisions</title> <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. +<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> @@ -40,7 +40,7 @@ of thumb could be used as a guideline: 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"/>). + <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. @@ -52,8 +52,8 @@ of thumb could be used as a guideline: 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>repoman commit - --straight-to-stable</c> option should be used. + 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> <li> @@ -67,13 +67,20 @@ of thumb could be used as a guideline: <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> - adding a missing build-time dependency that contributed to - a successfully yet incorrect build (e.g. missing some feature), + restricting a runtime dependency version, unless the <c>:=</c> + subslot operator is going to trigger a rebuild, </li> <li> - restricting a runtime dependency version, unless the <c>:=</c> - subslot operator is going to trigger a rebuild. + 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> @@ -82,7 +89,11 @@ of thumb could be used as a guideline: <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), + 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> @@ -92,18 +103,25 @@ of thumb could be used as a guideline: is expected soon), </li> <li> - adding a missing build-time dependency that caused a build failure, + 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> - adding a new USE flag or removing an existing one (since change - in USE flags is going to trigger <c>--changed-use</c> rebuild), + 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). + a dependency change that is a result of a package move (slot move), </li> </ul> diff --git a/general-concepts/emerge-and-ebuild/text.xml b/general-concepts/emerge-and-ebuild/text.xml index d96d5b0..87605a2 100644 --- a/general-concepts/emerge-and-ebuild/text.xml +++ b/general-concepts/emerge-and-ebuild/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>Emerge and ebuild relationships</title> <body> 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 e76cdcc..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> @@ -19,7 +19,7 @@ The basic filesystem layout and purpose is as follows: <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> @@ -51,7 +51,7 @@ 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> diff --git a/general-concepts/git-to-rsync/text.xml b/general-concepts/git-to-rsync/text.xml index 354c555..455cf13 100644 --- a/general-concepts/git-to-rsync/text.xml +++ b/general-concepts/git-to-rsync/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/git-to-rsync/"> <chapter> <title>Git to RSYNC</title> @@ -30,7 +30,7 @@ </ul> <figure short="Git to RSYNC Propagation" link="diagram.png" - caption="Diagram showing Git to RSYNC Propagation" /> + caption="Diagram showing Git to RSYNC propagation" /> <p> The <c>emerge-websync</c> snapshot is made daily from the staging box. diff --git a/general-concepts/install-destinations/text.xml b/general-concepts/install-destinations/text.xml index cf9c278..57db917 100644 --- a/general-concepts/install-destinations/text.xml +++ b/general-concepts/install-destinations/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/install-destinations/"> <chapter> -<title>Install Destinations</title> +<title>Install destinations</title> <body> diff --git a/general-concepts/licenses/text.xml b/general-concepts/licenses/text.xml index 2153a39..655175a 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> @@ -14,7 +14,8 @@ match files existing in the repository's <c>licenses/</c> directory. 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. +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> @@ -225,17 +226,18 @@ indicates <c>GPL-2+</c> license: </section> <section> -<title>Adding New Licenses</title> +<title>Adding new licenses</title> <body> <p> -If your package's license is not already in the tree, you must add the -license before committing the package. When adding the license, use a -plain text file (UTF-8 encoded) if at all possible. Some licenses are -PDF files rather than plain text <d/> this should only be done if we -are legally required to do so. +If your package's license is not already in the tree, you must add the license +before committing the package. When adding the license, use a plain text file +(UTF-8 encoded), because non-text files +<uri link="::general-concepts/tree/#What Belongs in the Tree?">do not belong +in the repository</uri>. 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 +as listed in the repository's <c>profiles/license_groups</c> file. For more +information see <uri link="https://www.gentoo.org/glep/glep-0023.html">GLEP 23</uri>. </p> diff --git a/general-concepts/mailing-lists/text.xml b/general-concepts/mailing-lists/text.xml new file mode 100644 index 0000000..f91d1cf --- /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 06fef9a..eb0d700 100644 --- a/general-concepts/manifest/text.xml +++ b/general-concepts/manifest/text.xml @@ -1,10 +1,10 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/manifest/"> <chapter> <title>Manifest</title> <section> -<title>Generating the Manifest</title> +<title>Generating the Manifest file</title> <body> <p> In the tree, every package has a <c>Manifest</c> file. This file lives @@ -15,8 +15,8 @@ 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> -or <c>repoman manifest</c>. You may want to set <c>GENTOO_MIRRORS=</c> while +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> @@ -39,6 +39,42 @@ action from developers. </p> </body> </subsection> + +<subsection> +<title>Updating Manifest files</title> +<body> + +<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> +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> + +<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> +Special care is also required with regard to +<uri link="::general-concepts/mirrors/#Replacing automatically mirrored files"> +mirrors</uri>. +</p> +</body> +</subsection> </section> </chapter> </guide> diff --git a/general-concepts/mirrors/text.xml b/general-concepts/mirrors/text.xml index 61b8618..5bc8f73 100644 --- a/general-concepts/mirrors/text.xml +++ b/general-concepts/mirrors/text.xml @@ -1,10 +1,10 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/mirrors/"> <chapter> <title>Mirrors</title> <section> -<title>Automatic Mirroring</title> +<title>Automatic mirroring</title> <body> <p> @@ -22,7 +22,7 @@ rearranged, tidied out or having files modified. </body> <subsection> -<title>Restricting Automatic Mirroring</title> +<title>Restricting automatic mirroring</title> <body> <p> Three <c>RESTRICT</c> keywords can be used to control the mirroring process. @@ -41,15 +41,16 @@ This should not be used in new ebuilds. <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> <subsection> -<title>Replacing Automatically Mirrored Files</title> +<title>Replacing automatically mirrored files</title> <body> <p> On rare occasions you may need to replace a file that is already mirrored. @@ -68,13 +69,9 @@ fetch and start distributing the new version. </p> <p> -Please note that if upstream made any changes affecting the built -package, 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. +Updating an existing distfile is generally cause for concern and must be done +with care, see +<uri link="::general-concepts/manifest/#Updating Manifest files"/>. </p> <p> @@ -87,7 +84,7 @@ Infrastructure project's Distfile Mirroring System page</uri>. <subsection> -<title>Suitable Download Hosts</title> +<title>Suitable download hosts</title> <body> <p> If you have to host a source file (patch or tarball) yourself, as long as it @@ -100,15 +97,16 @@ 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. An example <c>SRC_URI</c> referencing -a distfile mirrored this way is as follows: +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> <codesample lang="ebuild"> @@ -119,29 +117,18 @@ SRC_URI="https://dev.gentoo.org/~myname/distfiles/${P}.tar.gz" where <c>myname</c> refers to the username of the developer. </p> -</body> -</subsection> -</section> - -<section> -<title>Gentoo Mirrors</title> - -<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>. The file should appear -on the mirrors within four hours (note that this is <e>less -frequent</e> than <uri link="::general-concepts/git-to-rsync"/>). - 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> +<title>Mirroring process</title> <body> <figure short="Mirroring Process" link="diagram.png" diff --git a/general-concepts/news/text.xml b/general-concepts/news/text.xml index 06b5866..88fb12b 100644 --- a/general-concepts/news/text.xml +++ b/general-concepts/news/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/news/"> <chapter> -<title>News Items</title> +<title>News items</title> <body> <p> diff --git a/general-concepts/overlay/text.xml b/general-concepts/overlay/text.xml index a180c88..77e7190 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> @@ -11,9 +11,9 @@ in one or more repos.conf files. </p> <p> -The overlay should contain the same directory structure as <c>PORTDIR</c> (although -only the necessary directories need be included). For example, a simple overlay -might have a directory structure like: +The overlay should contain the same directory structure as the Gentoo +repository (although only the necessary directories need be included). +For example, a simple overlay might have a directory structure like: </p> <pre> @@ -34,7 +34,7 @@ override existing entries. </body> <section> -<title>Overlay and Eclasses</title> +<title>Overlay and eclasses</title> <body> <p> diff --git a/general-concepts/package-collisions/text.xml b/general-concepts/package-collisions/text.xml index 7b1b5f8..0b168b5 100644 --- a/general-concepts/package-collisions/text.xml +++ b/general-concepts/package-collisions/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/package-collisions/"> <chapter> -<title>Package Collisions</title> +<title>Package collisions</title> <body> <p> diff --git a/general-concepts/package-maintainers/text.xml b/general-concepts/package-maintainers/text.xml index 6684e38..0773859 100644 --- a/general-concepts/package-maintainers/text.xml +++ b/general-concepts/package-maintainers/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/package-maintainers/"> <chapter> -<title>Package Maintainers</title> +<title>Package maintainers</title> <body> <p> 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 4839fa0..2b40d26 100644 --- a/general-concepts/portage-cache/text.xml +++ b/general-concepts/portage-cache/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/portage-cache/"> <chapter> -<title>The Portage Cache</title> +<title>The Portage cache</title> <body> <p> @@ -12,6 +12,11 @@ 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> @@ -25,8 +30,8 @@ fi </codesample> <p> -However, this is legal, since <c>eapi7-ver.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"> @@ -49,7 +54,7 @@ fi </body> <section> -<title>Conditional Inherits</title> +<title>Conditional inherits</title> <body> <p> Because eclasses modify various cached variables, conditional inheritance is not diff --git a/general-concepts/projects/text.xml b/general-concepts/projects/text.xml index c0a28ca..203c364 100644 --- a/general-concepts/projects/text.xml +++ b/general-concepts/projects/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/projects/"> <chapter> <title>Projects</title> @@ -21,7 +21,7 @@ form a project hierarchy. <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>. +<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 @@ -30,7 +30,7 @@ api.gentoo.org</uri> or on the </body> <section> -<title>Starting New Projects</title> +<title>Starting new projects</title> <body> <p> @@ -62,7 +62,7 @@ project with the same goals. </section> <section> -<title>Joining and Leaving a Project</title> +<title>Joining and leaving a project</title> <body> <p> @@ -72,7 +72,14 @@ 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. +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> diff --git a/general-concepts/sandbox/text.xml b/general-concepts/sandbox/text.xml index 8fd63a4..06da4d3 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> @@ -22,7 +22,7 @@ generally <b>not</b> the correct solution. <p> See <uri link="::function-reference/sandbox-functions/"/> for details on sandbox-related functions. See <uri -link="::appendices/common-problems/#Handling Access Violations"/> for suggestions +link="::appendices/common-problems/#Handling access violations"/> for suggestions on fixing sandbox-related build problems. </p> </body> diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml index d1adee1..f45263f 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> @@ -41,12 +41,12 @@ 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> <section> -<title>Sub-Slots</title> +<title>Sub-slots</title> <body> <p> @@ -55,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> @@ -78,30 +179,49 @@ 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> -<title>Slot Names</title> +<title>Slot names</title> <body> <p> -Current versions of portage accept slot and sub-slot names that begin with an +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> diff --git a/general-concepts/text.xml b/general-concepts/text.xml index ace731e..5f7f094 100644 --- a/general-concepts/text.xml +++ b/general-concepts/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/"> <chapter> -<title>General Concepts</title> +<title>General concepts</title> <body> <p> @@ -22,14 +22,15 @@ writing ebuilds or working with the Gentoo repository. <!-- Keep in alphabetical order --> <include href="autotools/"/> <include href="config-protect/"/> +<include href="copyright-policy/"/> <include href="dependencies/"/> <include href="ebuild-revisions/"/> <include href="emerge-and-ebuild/"/> -<include href="features/"/> <include href="filesystem/"/> <include href="git-to-rsync/"/> <include href="install-destinations/"/> <include href="licenses/"/> +<include href="mailing-lists/"/> <include href="manifest/"/> <include href="mirrors/"/> <include href="news/"/> diff --git a/general-concepts/tree/text.xml b/general-concepts/tree/text.xml index 4d2bf64..f1877fd 100644 --- a/general-concepts/tree/text.xml +++ b/general-concepts/tree/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/tree/"> <chapter> -<title>The Gentoo Repository</title> +<title>The Gentoo repository</title> <body> <p> @@ -41,7 +41,7 @@ The basic layout of the Gentoo repository is as follows: 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> + <uri link="::general-concepts/git-to-rsync/">Git to Rsync</uri> process. <ul> <li> @@ -80,7 +80,7 @@ The basic layout of the Gentoo repository is as follows: </body> <section> -<title>What Belongs in the Tree?</title> +<title>What belongs in the tree?</title> <body> <p> @@ -102,7 +102,7 @@ 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 +<uri link="::ebuild-writing/variables/#Renaming sources">renamed</uri> using <c>-></c> syntax. </p> diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml index dd9b3fd..2b893df 100644 --- a/general-concepts/use-flags/text.xml +++ b/general-concepts/use-flags/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/use-flags/"> <chapter> -<title>USE Flags</title> +<title>USE flags</title> <body> <p> @@ -82,10 +82,10 @@ instead, or controlled by a flag such as <c>minimal</c>. </p> <p> -You should not introduce USE flags that merely manipulate <c>CFLAGS</c>, -<c>FEATURES</c> or similar variables configured directly by the user. Instead, -packages should avoid manipulating them at all, and let users set them directly. -Common mistakes include: +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> @@ -97,8 +97,8 @@ Common mistakes include: </li> <li> - Introducing <c>lto</c> flag to force <c>-flto</c>. This is something user - should set directly in flag varibles. + Introducing <c>lto</c> flag to force <c>-flto</c>. This is something the user + should set directly in flag variables. </li> <li> @@ -114,13 +114,14 @@ 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. +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> +<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 @@ -203,6 +204,18 @@ 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 @@ -217,14 +230,14 @@ on USE-ordering in Portage. EAPI=7 -IUSE="foo +bar" +IUSE="+bar foo" </codesample> </body> </section> <section> -<title>Local and Global USE Flags</title> +<title>Local and global USE flags</title> <body> <p> @@ -256,7 +269,7 @@ gentoo-dev mailing list. </section> <section> -<title>USE Flag Descriptions</title> +<title>USE flag descriptions</title> <body> <p> All USE flags must be described in either <c>use.desc</c> in the @@ -281,7 +294,7 @@ for the format, and remember to keep them sorted. </section> <section> -<title>Conflicting USE Flags</title> +<title>Conflicting USE flags</title> <body> <p> Occasionally, ebuilds will have conflicting USE flags for functionality. @@ -297,22 +310,18 @@ GnuTLS is more featureful than OpenSSL, it is favoured: </p> <codesample lang="ebuild"> -src_compile() { +src_configure() { 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" + if use ssl; then + myconf+=" --enable-ssl --with-ssl=$(usex gnutls gnutls openssl)" else - myconf="${myconf} --disable-ssl" + myconf+=" --disable-ssl" fi econf \ # Other stuff ${myconf} - - emake } </codesample> @@ -342,7 +351,7 @@ needs. </section> <section> -<title>USE_EXPAND and ARCH USE Flags</title> +<title>USE_EXPAND and ARCH USE flags</title> <body> <p> diff --git a/general-concepts/user-environment/text.xml b/general-concepts/user-environment/text.xml index c2c02e7..5635a3f 100644 --- a/general-concepts/user-environment/text.xml +++ b/general-concepts/user-environment/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="general-concepts/user-environment/"> <chapter> -<title>User Environment</title> +<title>User environment</title> <body> <p> @@ -16,7 +16,7 @@ performed upon the environment. </body> <section> -<title>Filtering Variables</title> +<title>Filtering variables</title> <body> <p> Certain variables will really really upset certain build systems. A good example @@ -42,7 +42,7 @@ pkg_setup() { </section> <section> -<title>Not Filtering Variables</title> +<title>Not filtering variables</title> <body> <p> On the other hand, it is extremely important that certain user preferences are diff --git a/general-concepts/virtuals/text.xml b/general-concepts/virtuals/text.xml index 377933f..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> @@ -24,17 +24,17 @@ An example of a virtual: </p> <codesample lang="ebuild"> -EAPI=7 +EAPI=8 DESCRIPTION="Virtual for C++ tr1 <type_traits>" SLOT="0" -KEYWORDS="alpha amd64 arm hppa ia64 ~mips ppc ppc64 ~s390 sparc x86 ~x64-macos" +KEYWORDS="~alpha amd64 arm hppa ~ia64 ~mips ppc ppc64 ~s390 sparc x86 ~x64-macos" RDEPEND="|| ( >=sys-devel/gcc-4.1 dev-libs/boost )" </codesample> <p> -Looks familar...right? It should since its going to look just like a regular +Looks familar...right? It should since it's going to look just like a regular ebuild. </p> @@ -95,7 +95,7 @@ For example, a virtual for different packages providing ABI-compatible </p> <codesample lang="ebuild"> -EAPI=6 +EAPI=8 DESCRIPTION="Virtual for libfoo.so.1" SLOT="0/1" @@ -124,10 +124,11 @@ would contain: </p> <codesample lang="ebuild"> -EAPI=6 +EAPI=8 DESCRIPTION="Virtual for libfoo.so.0" SLOT="0/0" + RDEPEND="dev-libs/libfoo:0/0" </codesample> @@ -136,10 +137,11 @@ while <c>virtual/libfoo-1.ebuild</c> would contain: </p> <codesample lang="ebuild"> -EAPI=6 +EAPI=8 DESCRIPTION="Virtual for libfoo.so.1" SLOT="0/1" + RDEPEND="dev-libs/newfoo:0/1" </codesample> diff --git a/hosted-projects/text.xml b/hosted-projects/text.xml index 2521622..8ce75b3 100644 --- a/hosted-projects/text.xml +++ b/hosted-projects/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="hosted-projects/"> <chapter> -<title>Hosted Projects</title> +<title>Hosted projects</title> <body> <p> @@ -11,7 +11,7 @@ prevent a repeat of the <c>genkernel</c> disaster. </body> <section> -<title>Documentation Requirement</title> +<title>Documentation requirement</title> <body> <p> @@ -21,7 +21,7 @@ and not left as "something we'll do later (honest)". </p> <p> -Our documentation team are happy to help out with GuideXMLification, translation +Our documentation team is happy to help out with GuideXMLification, translation etc. for the user documentation, but they <e>need</e> various things to do this: </p> @@ -108,7 +108,7 @@ In practice, this means the following: </section> <section> -<title>Open / Free</title> +<title>Open / free</title> <body> <p> diff --git a/keywording/text.xml b/keywording/text.xml index 1c5f71d..4360b49 100644 --- a/keywording/text.xml +++ b/keywording/text.xml @@ -1,14 +1,14 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="keywording/"> <chapter> -<title>Keywording and Stabilization</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> @@ -38,14 +38,14 @@ 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> - 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. + 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> The package version and the ebuild are believed to work and do not have any @@ -53,7 +53,7 @@ The different levels of keyword are: is considered suitable for <c>arch</c>. </dd> <dt> - No keyword + No keyword ("unkeyworded") </dt> <dd> If a package has no keyword for a given arch, it means it is not known @@ -72,9 +72,10 @@ The different levels of keyword are: </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>ppc</c> and <c>x86</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"> @@ -82,9 +83,9 @@ KEYWORDS="-* ppc x86" </codesample> <p> -This is different in implication from <c>"ppc x86"</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> @@ -94,39 +95,39 @@ Do <b>not</b> use the <c>*</c> or <c>~*</c> special keywords in ebuilds. <note> Usually, "live" ebuilds (see <uri link="::ebuild-writing/functions/src_unpack/vcs-sources/"/>) -do not specify a <c>KEYWORDS</c> variable, or assign the empty string to it. +do not specify a <c>KEYWORDS</c> variable. </note> </body> <section> -<title>Equal Visibility Requirement</title> +<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> </section> <section> -<title>Hard Masks</title> +<title>Hard masks</title> <body> <p> @@ -138,66 +139,77 @@ 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> </section> <section> -<title>Keywording New Packages</title> +<title>Keywording new packages</title> <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, 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> </section> <section> -<title>Keywording on Upgrades</title> +<title>Keywording on upgrades</title> <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> @@ -212,20 +224,24 @@ 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 new bug to the architecture in question regarding this if no bug is already -available. +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> -If there are no new dependencies, do not remove keywords if your commit fails -with repoman <d/> please try a full <c>git pull</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 git commit message. +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 +See <uri link="::ebuild-maintenance/git/#Git commit message format"/> for how to do this. </important> @@ -237,10 +253,34 @@ to do this. <body> <p> -Stabilization, i.e., moving an ebuild from <c>~arch</c> to <c>arch</c>, 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. +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> @@ -248,12 +288,53 @@ 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 do it manually, or they can fill the package +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. -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. +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> @@ -281,15 +362,15 @@ for further details): 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="https://www.gentoo.org/support/security/vulnerability-treatment-policy.html"> -Vulnerability Treatment Policy</uri> +Vulnerability Treatment Policy</uri>. </p> </body> @@ -299,38 +380,82 @@ Vulnerability Treatment Policy</uri> <body> <p> -AMD64, X86: If you are the maintainer of a package and own the respective amd64 -or x86 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 x86 using a -<uri link="https://wiki.gentoo.org/wiki/Project:AMD64/32-bit_Chroot_Guide"> -specialized environment on amd64</uri>. +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> -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. +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> -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. +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> -Exotic architectures (like hppa, ia64, ppc*, sparc) are short on manpower, -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). +Maintainers need some method or system to organize and start pending +stabilizations once they become due. </p> <p> -Some architectures (like mips, riscv) do not maintain a stable keyword. -So packages are not to be marked stable for one of these architectures. +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> @@ -340,15 +465,15 @@ So packages are not to be marked stable for one of these architectures. <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 +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> in addition to <c>STABLEREQ</c> and CC the -arches that you would like to stabilize. +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 +<c><stabilize-allarches/></c> tag to metadata.xml. This allows consistency in future stabilizations and saves arch teams considerable work. </p> @@ -360,12 +485,19 @@ 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> -<title>Removing Package Versions</title> +<title>Removing package versions</title> <body> <p> @@ -376,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. @@ -386,7 +518,7 @@ 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> diff --git a/profiles/categories/text.xml b/profiles/categories/text.xml index 6a4de2d..81079b2 100644 --- a/profiles/categories/text.xml +++ b/profiles/categories/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/categories/"> <chapter> -<title>Profiles <c>categories</c> File</title> +<title>Profiles <c>categories</c> file</title> <body> <p> @@ -11,8 +11,12 @@ 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"/>. +link="::ebuild-writing/misc-files/metadata/#Category metadata"/>. </p> </body> diff --git a/profiles/info_files/text.xml b/profiles/info_files/text.xml index ae68b30..22f9cd2 100644 --- a/profiles/info_files/text.xml +++ b/profiles/info_files/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/info_files/"> <chapter> -<title>Profiles <c>info_</c> Files</title> +<title>Profiles <c>info_</c> files</title> <body> <p> diff --git a/profiles/make.defaults/text.xml b/profiles/make.defaults/text.xml index 03aa8db..18221d4 100644 --- a/profiles/make.defaults/text.xml +++ b/profiles/make.defaults/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>Profiles <c>make.defaults</c> file</title> <body> <p> diff --git a/profiles/package.mask/text.xml b/profiles/package.mask/text.xml index 6cef26d..9b6bc1d 100644 --- a/profiles/package.mask/text.xml +++ b/profiles/package.mask/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>Profiles <c>package.mask</c> file</title> <body> <p> @@ -15,6 +15,31 @@ 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> This file can be used in subprofiles to mask packages only for certain setups. </p> diff --git a/profiles/packages/text.xml b/profiles/packages/text.xml index 13f98ab..3ae80e4 100644 --- a/profiles/packages/text.xml +++ b/profiles/packages/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/packages/"> <chapter> -<title>Profiles <c>packages</c> File</title> +<title>Profiles <c>packages</c> file</title> <body> <p> diff --git a/profiles/text.xml b/profiles/text.xml index 3269d33..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> diff --git a/profiles/updates/text.xml b/profiles/updates/text.xml index 7136aea..6e44507 100644 --- a/profiles/updates/text.xml +++ b/profiles/updates/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="profiles/updates/"> <chapter> -<title>Profiles <c>updates/</c> Directory</title> +<title>Profiles <c>updates/</c> directory</title> <body> <p> diff --git a/profiles/use.desc/text.xml b/profiles/use.desc/text.xml index 87df40c..0a4e9a3 100644 --- a/profiles/use.desc/text.xml +++ b/profiles/use.desc/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>Profiles <c>use.desc</c> and <c>use.local.desc</c> files</title> <body> <p> @@ -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">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..543d439 100644 --- a/profiles/use.mask/text.xml +++ b/profiles/use.mask/text.xml @@ -1,7 +1,7 @@ -<?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> +<title>Profiles <c>use.mask</c> file</title> <body> <p> @@ -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,11 +32,13 @@ 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> -See <uri link="::general-concepts/use-flags/#noblah USE Flags"/> for more discussion. +See <uri link="::general-concepts/use-flags/#noblah USE flags"/> for more discussion. </p> </body> diff --git a/quickstart/text.xml b/quickstart/text.xml index 09dbaad..32e3ede 100644 --- a/quickstart/text.xml +++ b/quickstart/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="quickstart/"> <chapter> -<title>Quickstart Ebuild Guide</title> +<title>Quickstart ebuild guide</title> <body> <p> @@ -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> @@ -24,7 +25,7 @@ have had several parts chopped out, changed and simplified. </body> <section> -<title>First Ebuild</title> +<title>First ebuild</title> <body> <p> @@ -37,7 +38,7 @@ can see real ebuilds in the main tree). # Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -EAPI=6 +EAPI=8 DESCRIPTION="Exuberant ctags generates tags files for quick source navigation" HOMEPAGE="https://ctags.io/ https://github.com/universal-ctags/ctags" @@ -60,7 +61,7 @@ src_install() { </body> <subsection> -<title>Basic Format</title> +<title>Basic format</title> <body> <p> @@ -73,14 +74,14 @@ 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> <subsection> -<title>Information Variables</title> +<title>Information variables</title> <body> <p> @@ -89,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> @@ -118,20 +119,20 @@ or (at your option) any later version). <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"/>. +<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> <subsection> -<title>Build Functions</title> +<title>Build functions</title> <body> <p> @@ -147,8 +148,8 @@ 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> @@ -164,7 +165,8 @@ 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 @@ -187,13 +189,13 @@ failed. </section> <section> -<title>Ebuild with Dependencies</title> +<title>Ebuild with dependencies</title> <body> <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,7 +208,7 @@ Here's <c>app-misc/detox/detox-1.1.1.ebuild</c>: # Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -EAPI=5 +EAPI=8 DESCRIPTION="detox safely removes spaces and strange characters from filenames" HOMEPAGE="http://detox.sourceforge.net/" @@ -218,8 +220,8 @@ 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 @@ -231,7 +233,7 @@ 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> @@ -241,22 +243,25 @@ 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> </section> <section> -<title>Ebuild with Patches</title> +<title>Ebuild with patches</title> <body> <p> -Often we need to apply patches. This is done in the <c>src_prepare</c> -function using the <c>eapply</c> helper function. To use <c>eapply</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> @@ -264,7 +269,7 @@ one must use EAPI 7. Here's <c>app-misc/detox/detox-1.1.0.ebuild</c>: # Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -EAPI=7 +EAPI=8 DESCRIPTION="detox safely removes spaces and strange characters from filenames" HOMEPAGE="http://detox.sourceforge.net/" @@ -276,8 +281,8 @@ 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() { eapply "${FILESDIR}"/${P}-destdir.patch \ @@ -295,8 +300,9 @@ 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 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/#Suitable download hosts"/> and +<uri link="::ebuild-writing/functions/src_prepare/eapply/"/>. </p> <p> @@ -308,7 +314,7 @@ that <c>eapply_user</c> is called. </section> <section> -<title>Ebuild with USE Flags</title> +<title>Ebuild with USE flags</title> <body> <p> @@ -317,10 +323,10 @@ replacement iconv for <c>libc</c> implementations which don't have their own. </p> <codesample lang="ebuild"> -# Copyright 1999-2021 Gentoo Authors +# Copyright 1999-2022 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -EAPI=5 +EAPI=8 DESCRIPTION="GNU charset conversion library for libc which doesn't implement it" HOMEPAGE="https://www.gnu.org/software/libiconv/" @@ -331,7 +337,8 @@ 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) @@ -359,7 +366,7 @@ Another more complicated example, this time based upon # Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -EAPI=7 +EAPI=8 inherit desktop @@ -369,7 +376,7 @@ SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2" 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* @@ -381,15 +388,14 @@ RDEPEND="=x11-libs/gtk+-2* xface? ( >=media-libs/compface-1.4 ) app-misc/mime-types x11-misc/shared-mime-info" -DEPEND="${RDEPEND} - dev-util/pkgconfig +DEPEND="${RDEPEND}" +BDEPEND="dev-util/pkgconfig nls? ( >=sys-devel/gettext-0.12.1 )" -src_prepare() { - eapply "${FILESDIR}"/${PN}-namespace.diff \ - "${FILESDIR}"/${PN}-procmime.diff - eapply_user -} +PATCHES=( + "${FILESDIR}"/${PN}-namespace.patch + "${FILESDIR}"/${PN}-procmime.patch +) src_configure() { econf \ diff --git a/tasks-reference/completion/text.xml b/tasks-reference/completion/text.xml index 8d48003..d4e6daf 100644 --- a/tasks-reference/completion/text.xml +++ b/tasks-reference/completion/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tasks-reference/completion/"> <chapter> -<title>Completion Files</title> +<title>Completion files</title> <body> <p> @@ -14,7 +14,7 @@ for how to install completion files. </body> <section> -<title>Completion-Related Internal Bash Variables</title> +<title>Completion-related internal Bash variables</title> <body> <p> @@ -92,7 +92,7 @@ are subsequently reset. </section> <section> -<title>Completion-Related Bash Builtins</title> +<title>Completion-related Bash builtins</title> <body> <p> @@ -154,7 +154,7 @@ complete -o nospace -d cd </section> <section> -<title>Anatomy of a Completion Function</title> +<title>Anatomy of a completion function</title> <body> <p> @@ -296,7 +296,7 @@ esac </section> <section> -<title>Real-World Example</title> +<title>Real-world example</title> <body> <p> diff --git a/tasks-reference/environment/text.xml b/tasks-reference/environment/text.xml index ff4c14c..b37b991 100644 --- a/tasks-reference/environment/text.xml +++ b/tasks-reference/environment/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tasks-reference/environment/"> <chapter> -<title>Environment Files</title> +<title>Environment files</title> <body> diff --git a/tasks-reference/init-scripts/text.xml b/tasks-reference/init-scripts/text.xml index e76670c..a46758e 100644 --- a/tasks-reference/init-scripts/text.xml +++ b/tasks-reference/init-scripts/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tasks-reference/init-scripts/"> <chapter> -<title>Init Scripts</title> +<title>Init scripts</title> <body> @@ -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 62c8ec0..3094b20 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> @@ -19,7 +19,7 @@ modules which will provide authentication. </body> <section> -<title>Structure of a <c>pamd</c> File</title> +<title>Structure of a <c>pamd</c> file</title> <body> <p> @@ -115,7 +115,7 @@ The statement is composed of 3 or 4 tokens: <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 @@ -160,7 +160,7 @@ and takes care of executing it. </section> <section> -<title>Installing <c>pamd</c> Files</title> +<title>Installing <c>pamd</c> files</title> <body> <p> @@ -215,7 +215,7 @@ which just uses <c>system-auth</c> login class. </section> <section> -<title>Installing PAM Modules</title> +<title>Installing PAM modules</title> <body> <p> diff --git a/tasks-reference/text.xml b/tasks-reference/text.xml index 5137b4d..47ffb76 100644 --- a/tasks-reference/text.xml +++ b/tasks-reference/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tasks-reference/"> <chapter> -<title>Tasks Reference</title> +<title>Tasks reference</title> <body> <p> @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide root="true"> <chapter> -<title>Master Index</title> +<title>Master index</title> <body> <p> @@ -10,14 +10,14 @@ 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=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>. -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> </body> @@ -30,7 +30,7 @@ section lists specific contributions to this manual. </section> <section> -<title>Full Contents</title> +<title>Full contents</title> <body> <contentsTree/> </body> diff --git a/tools-reference/bash/text.xml b/tools-reference/bash/text.xml index 77b5298..57c3d56 100644 --- a/tools-reference/bash/text.xml +++ b/tools-reference/bash/text.xml @@ -1,7 +1,7 @@ -<?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> @@ -11,10 +11,10 @@ ebuilds. </body> <section> -<title>Bash Conditionals</title> +<title>Bash conditionals</title> <subsection> -<title>Basic Selection</title> +<title>Basic selection</title> <body> <p> @@ -31,7 +31,7 @@ fi </subsection> <subsection> -<title>Multiple Selection</title> +<title>Multiple selection</title> <body> <p> @@ -82,28 +82,28 @@ fi </subsection> <subsection> -<title>Selection Tests</title> +<title>Selection tests</title> <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 +# is ${foo} zero length? +if [[ -z ${foo} ]] ; then die "Please set foo" fi -# is $foo equal to "moo"? -if [[ "${foo}" == "moo" ]] ; then +# 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> @@ -111,7 +111,7 @@ fi </subsection> <subsection> -<title>Single versus Double Brackets in <c>bash</c></title> +<title>Single versus double brackets in <c>bash</c></title> <body> <important> @@ -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 <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> @@ -136,7 +144,7 @@ bash$ </subsection> <subsection> -<title>String Comparison in <c>bash</c></title> +<title>String comparison in <c>bash</c></title> <body> <p> @@ -145,61 +153,37 @@ 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> </subsection> <subsection> -<title>String Tests in <c>bash</c></title> +<title>String tests in <c>bash</c></title> <body> <p> @@ -208,43 +192,25 @@ 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> <subsection> -<title>Integer Comparison in <c>bash</c></title> +<title>Integer comparison in <c>bash</c></title> <body> <p> @@ -253,69 +219,41 @@ 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> </subsection> <subsection> -<title>File Tests in <c>bash</c></title> +<title>File tests in <c>bash</c></title> <body> <p> @@ -324,239 +262,135 @@ 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> </subsection> <subsection> -<title>File Comparison in <c>bash</c></title> +<title>File comparison in <c>bash</c></title> <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> </subsection> <subsection> -<title>Boolean Algebra in <c>bash</c></title> +<title>Boolean algebra in <c>bash</c></title> <body> <p> @@ -566,39 +400,23 @@ 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> @@ -620,7 +438,7 @@ These should be avoided in favour of <c>[[ ]]</c> and the above operators. </section> <section> -<title>Bash Iterative Structures</title> +<title>Bash iterative structures</title> <body> <p> @@ -668,7 +486,7 @@ done < some_file </codesample> <p> -See <uri link="::ebuild-writing/error-handling/#die and Subshells"/> +See <uri link="::ebuild-writing/error-handling/#die and subshells"/> for an explanation of why <c>while read < file</c> should be used over <c>cat file | while read</c>. </p> @@ -677,7 +495,7 @@ be used over <c>cat file | while read</c>. </section> <section> -<title>Bash Variable Manipulation</title> +<title>Bash variable manipulation</title> <body> <p> @@ -689,7 +507,7 @@ and friends. </body> <subsection> -<title><c>bash</c> String Length</title> +<title><c>bash</c> string length</title> <body> <p> @@ -706,7 +524,7 @@ echo "${somevar} is ${#somevar} characters long" </subsection> <subsection> -<title><c>bash</c> Variable Default Values</title> +<title><c>bash</c> variable default values</title> <body> <p> @@ -736,7 +554,7 @@ or a blank string otherwise. There is a <c>${var+value}</c> form. </subsection> <subsection> -<title><c>bash</c> Substring Extraction</title> +<title><c>bash</c> substring extraction</title> <body> <p> @@ -769,7 +587,7 @@ than zero. Again, negative <c>offset</c> values must be given as an expression. </subsection> <subsection> -<title><c>bash</c> Command Substitution</title> +<title><c>bash</c> command substitution</title> <body> <p> @@ -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"> @@ -790,7 +608,7 @@ myconf="$(use_enable acl) $(use_enable nls) --with-tlib=ncurses" </subsection> <subsection> -<title><c>bash</c> String Replacements</title> +<title><c>bash</c> string replacements</title> <body> <p> @@ -849,24 +667,71 @@ 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> <subsection> -<title><c>bash</c> Arithmetic Expansion</title> +<title><c>bash</c> arithmetic expansion</title> <body> <p> @@ -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> diff --git a/tools-reference/cat/text.xml b/tools-reference/cat/text.xml index a56de13..630a995 100644 --- a/tools-reference/cat/text.xml +++ b/tools-reference/cat/text.xml @@ -1,7 +1,7 @@ -<?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> @@ -41,7 +41,7 @@ be replaced by <c>cp -f foo bar</c>. </section> <section> -<title>Here Documents</title> +<title>Here documents</title> <body> <p> On the other hand, <c>cat</c> is exceptionally useful for so-called diff --git a/tools-reference/cut/text.xml b/tools-reference/cut/text.xml index fd1ac86..ce6130b 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> @@ -56,7 +56,7 @@ do_stuff | cut -c 2- </codesample> <p> -See the cut manpage and +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> diff --git a/tools-reference/diff-and-patch/text.xml b/tools-reference/diff-and-patch/text.xml index dcbbf18..7a5e932 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</c> and <c>patch</c> — File Differences</title> +<title><c>diff</c> and <c>patch</c> — file differences</title> <body> <p> @@ -30,20 +30,20 @@ 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, or <c>eapply</c> function -beginning with EAPI=6, instead — see -<uri link="::ebuild-writing/functions/src_prepare/epatch"/>. +ebuilds, use the <c>eapply</c> function instead <d/> see +<uri link="::ebuild-writing/functions/src_prepare/eapply/"/>. </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/echo/text.xml b/tools-reference/echo/text.xml index d88faa4..9a84ab9 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> @@ -20,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 @@ -40,7 +40,7 @@ describes the preferred way of dealing with such cases. </section> <section> -<title>Here Strings</title> +<title>Here strings</title> <body> <p> As of >=bash-2.05b, the so-called "here strings" have been @@ -86,7 +86,7 @@ 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> diff --git a/tools-reference/ekeyword/text.xml b/tools-reference/ekeyword/text.xml index 6326f9f..3a294d2 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 4367c5a..9a28640 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</c> and <c>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 b4fe5ef..5825a39 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> @@ -207,7 +207,7 @@ is not POSIX, see the table). </warning> <p> -See find-1 and +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> diff --git a/tools-reference/grep/text.xml b/tools-reference/grep/text.xml index a67123e..b0651bd 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> @@ -55,8 +55,8 @@ of <c>1</c> indicates no matches. <p> See <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/grep.html"> -IEEE Std 1003.1-2017-grep</uri> for details. The grep-1 manual page on GNU -systems documents many non-portable additional features. +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 b3e532f..436fdc1 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</c> and <c>tail</c> — Line Extraction</title> +<title><c>head</c> and <c>tail</c> — line extraction</title> <body> <p> @@ -23,8 +23,8 @@ Use of the GNU <c>-c</c> option is unportable and should be avoided. <p> For full details, see <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/head.html"> -IEEE Std 1003.1-2017-head</uri>. Note that head-1 on GNU systems describes -many non-portable options. +IEEE Std 1003.1-2017-head</uri>. Note that <c>head(1)</c> on GNU systems +describes many non-portable options. </p> <p> @@ -52,8 +52,8 @@ tail -n +6 in.txt > out.txt <p> For full details, see <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/tail.html"> -IEEE Std 1003.1-2017-tail</uri>. Note that tail-1 on GNU systems describes -many non-portable options. +IEEE Std 1003.1-2017-tail</uri>. Note that <c>tail(1)</c> on GNU systems +describes many non-portable options. </p> </body> diff --git a/tools-reference/sed/text.xml b/tools-reference/sed/text.xml index aac3524..da43c8f 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> @@ -65,12 +65,12 @@ constructs are specific to <c>GNU sed 4</c> <d/> on non-GNU userland archs, the 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> +<title>Basic <c>sed</c> invocation</title> <body> <p> @@ -104,7 +104,7 @@ The term <e>pattern</e> refers to the description of text being matched. </section> <section> -<title>Simple Text Substitution using <c>sed</c></title> +<title>Simple text substitution using <c>sed</c></title> <body> <p> @@ -132,7 +132,12 @@ The above will replace <c>irksome texting</c> with <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"> @@ -186,7 +191,7 @@ are used. </section> <section> -<title>Regular Expression Substitution using <c>sed</c></title> +<title>Regular expression substitution using <c>sed</c></title> <body> <p> @@ -344,7 +349,7 @@ not discussed in this document. </section> <section> -<title>Content Deletion using <c>sed</c></title> +<title>Content deletion using <c>sed</c></title> <body> <p> @@ -363,7 +368,7 @@ lines' contents but not the newline. </section> <section> -<title>Content Extraction using <c>sed</c></title> +<title>Content extraction using <c>sed</c></title> <body> <p> @@ -378,7 +383,7 @@ sometimes useful. </section> <section> -<title>Inserting Content using <c>sed</c></title> +<title>Inserting content using <c>sed</c></title> <body> <p> @@ -416,10 +421,10 @@ the file, for example, causing your sed script to break. </section> <section> -<title>Regular Expression Atoms in <c>sed</c></title> +<title>Regular expression atoms in <c>sed</c></title> <subsection> -<title>Basic Atoms</title> +<title>Basic atoms</title> <body> <table> @@ -541,7 +546,7 @@ the file, for example, causing your sed script to break. </subsection> <subsection> -<title>Character Class Shortcuts</title> +<title>Character class shortcuts</title> <body> <table> @@ -599,7 +604,7 @@ the file, for example, causing your sed script to break. </subsection> <subsection> -<title>POSIX Character Classes</title> +<title>POSIX character classes</title> <body> <p> @@ -709,7 +714,7 @@ Read the source, it's the only place these're documented properly... </subsection> <subsection> -<title>Count Specifiers</title> +<title>Count specifiers</title> <body> <table> @@ -776,7 +781,7 @@ Read the source, it's the only place these're documented properly... </section> <section> -<title>Replacement Atoms in <c>sed</c></title> +<title>Replacement atoms in <c>sed</c></title> <body> <table> @@ -850,7 +855,7 @@ Read the source, it's the only place these're documented properly... </section> <section> -<title>Details of <c>sed</c> Match Mechanics</title> +<title>Details of <c>sed</c> match mechanics</title> <body> <p> @@ -873,7 +878,7 @@ the pattern. </section> <section> -<title>Notes on Performance with <c>sed</c></title> +<title>Notes on performance with <c>sed</c></title> <body> <todo> @@ -884,14 +889,15 @@ write this </section> <section> -<title>Recommended Further Reading for Regular Expressions</title> +<title>Recommended further reading for regular expressions</title> <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> diff --git a/tools-reference/sort/text.xml b/tools-reference/sort/text.xml index e726be4..6f140d6 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> diff --git a/tools-reference/text.xml b/tools-reference/text.xml index 9e0f6bc..7ed3ce3 100644 --- a/tools-reference/text.xml +++ b/tools-reference/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="tools-reference/"> <chapter> -<title>Tools Reference</title> +<title>Tools reference</title> <body> <p> @@ -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> @@ -29,9 +35,6 @@ ebuilds. <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 1f09978..e688d89 100644 --- a/tools-reference/tr/text.xml +++ b/tools-reference/tr/text.xml @@ -1,7 +1,7 @@ -<?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> diff --git a/tools-reference/uniq/text.xml b/tools-reference/uniq/text.xml index 1b906f8..2114703 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> diff --git a/xsl/lang.highlight.c.xsl b/xsl/lang.highlight.c.xsl index 089de50..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" @@ -46,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 --> @@ -66,12 +67,17 @@ <!-- 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 bbf9c64..f615393 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,94 @@ <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 + <!-- 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 +121,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 +148,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 +164,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,269 +187,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> - - <!-- PMS keywords for EAPI4 --> - <xsl:when test="$data = 'docompress' or $data = 'nonfatal'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- PMS keywords for EAPI5 --> - <xsl:when test="$data = 'doheader' or $data = 'newheader' or $data = 'usex'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- PMS keywords for EAPI6 --> - <xsl:when test="$data = 'eapply' or $data = 'eapply_user' or $data = 'einstalldocs' or $data = 'get_libdir' or $data = 'in_iuse'"> - <span class="Statement"><xsl:value-of select="$data"/></span> - </xsl:when> - - <!-- PMS keywords for EAPI7 --> - <xsl:when test="$data = 'dostrip' or $data = 'eqawarn' or $data = 'ver_cut' or $data = 'ver_rs' or $data = 'ver_test'"> - <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> - <!-- Sandbox --> - <xsl:when test="$data = 'addread' or $data = 'addwrite' or $data = 'adddeny' or $data = 'addpredict'"> - <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> - <!-- 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> - - <!-- Default keywords phase functions --> - <xsl:when test="$data = 'default' or $data = 'default_pkg_nofetch' or $data = 'default_src_unpack' or - $data = 'default_src_prepare' or $data = 'default_src_configure' or $data = 'default_src_compile' or - $data = 'default_src_test' or $data = 'default_src_install'"> - <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> - - <!-- 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> - </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> - </xsl:when> - - <!-- eapi7-ver --> - <xsl:when test="$data = 'ver_rs' or $data = 'ver_cut' or $data = 'ver_test'"> - <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 --> @@ -379,25 +219,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 --> @@ -409,14 +251,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> @@ -426,18 +268,18 @@ </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> @@ -445,3 +287,7 @@ </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 e588761..3c3275d 100644 --- a/xsl/str.tokenize.function.xsl +++ b/xsl/str.tokenize.function.xsl @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?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 --> @@ -12,7 +12,7 @@ xmlns="http://www.w3.org/1999/xhtml"> <func:function name="str:tokenize_plasmaroo"> - <xsl:param name="string" select="''" /> + <xsl:param name="string" select="''" /> <xsl:param name="delimiters" select="' 	
'" /> <xsl:choose> <xsl:when test="not($string)"> @@ -70,7 +70,10 @@ </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> + <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"/> @@ -86,3 +89,8 @@ </xsl:template> </xsl:stylesheet> + +<!-- Local Variables: --> +<!-- indent-tabs-mode: nil --> +<!-- fill-column: 120 --> +<!-- End: --> |
