diff options
| -rw-r--r-- | devbook.xsl | 68 | ||||
| -rw-r--r-- | general-concepts/linguas/text.xml | 13 | ||||
| -rw-r--r-- | general-concepts/mirrors/diagram.png | bin | 0 -> 31779 bytes | |||
| -rw-r--r-- | general-concepts/mirrors/diagram.svg | 521 | ||||
| -rw-r--r-- | general-concepts/mirrors/text.xml | 89 | ||||
| -rw-r--r-- | general-concepts/overlay/text.xml | 52 | ||||
| -rw-r--r-- | general-concepts/pic/text.xml | 13 | ||||
| -rw-r--r-- | general-concepts/portage-cache/text.xml | 79 | ||||
| -rw-r--r-- | general-concepts/privileges/text.xml | 15 | ||||
| -rw-r--r-- | general-concepts/sandbox/text.xml | 30 | ||||
| -rw-r--r-- | general-concepts/slotting/text.xml | 52 | ||||
| -rw-r--r-- | general-concepts/text.xml | 10 | ||||
| -rw-r--r-- | general-concepts/tree/text.xml | 185 | ||||
| -rw-r--r-- | general-concepts/use-flags/text.xml | 230 | ||||
| -rw-r--r-- | general-concepts/user-environment/text.xml | 88 |
15 files changed, 1434 insertions, 11 deletions
diff --git a/devbook.xsl b/devbook.xsl index 886ea50..f30096b 100644 --- a/devbook.xsl +++ b/devbook.xsl @@ -13,6 +13,7 @@ </xsl:text> </xsl:variable> +<xsl:variable name="qvariable-start">$</xsl:variable> <xsl:variable name="variable-start">${</xsl:variable> <xsl:variable name="variable-end">}</xsl:variable> @@ -48,7 +49,10 @@ </xsl:when> <xsl:when test="substring($data, string-length($data)) = ')'"> - <xsl:value-of select="substring($data, 1, string-length($data)-1)"/><span class="PreProc">)</span> + <xsl:call-template name="highlight-subtokenate"> + <xsl:with-param name="data" select="substring($data, 1, string-length($data)-1)"/> + </xsl:call-template> + <span class="PreProc">)</span> </xsl:when> <!-- This must go before the other quote matchers --> @@ -66,15 +70,29 @@ <xsl:when test="substring($data, 1, 1) = '"'"> <span class="Statement">"</span> - <xsl:value-of select="substring($data, 2)"/> + <xsl:call-template name="highlight-subtokenate"> + <xsl:with-param name="data" select="substring($data, 2)"/> + </xsl:call-template> </xsl:when> <xsl:when test="substring($data, string-length($data)) = '"'"> - <xsl:value-of select="substring($data, 0, string-length($data))"/> + <xsl:call-template name="highlight-subtokenate"> + <xsl:with-param name="data" select="substring($data, 0, string-length($data))"/> + </xsl:call-template> <span class="Statement">"</span> </xsl:when> + <xsl:when test="substring($data, 1, 1) = $qvariable-start"> + <span class="Identifier">$<xsl:value-of select="substring($data, 2)"/></span> + </xsl:when> <!-- Functioney highlighing --> + + <!-- 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'"> + <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 @@ -304,7 +322,7 @@ <!-- No match return --> <xsl:otherwise> - <highlight-nomatch-sub><xsl:value-of select="$data"/></highlight-nomatch-sub> + <xsl:value-of select="$data"/> </xsl:otherwise> </xsl:choose> </xsl:template> @@ -326,7 +344,8 @@ <!-- 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) = $commentChar"> + <xsl:when test="($commentSeeker != 0 and position() > $commentSeeker) or substring(../*[position()=1], 1, 1) = $commentChar + or . = $commentChar"> <span class="Comment"><xsl:value-of select="."/></span> </xsl:when> @@ -347,7 +366,7 @@ </xsl:call-template> </xsl:when> - <xsl:when test=". = '{' or . = '}' or . = '\' or . = '(' or . = '#'"> + <xsl:when test=". = '{' or . = '}' or . = '\' or . = '('"> <span class="PreProc"><xsl:value-of select="."/></span> </xsl:when> @@ -367,20 +386,20 @@ </xsl:template> <xsl:template match="chapter"> - <h1><xsl:value-of select="title"/></h1> + <h1><xsl:apply-templates select="title"/></h1> <xsl:apply-templates select="(body|section)"/> </xsl:template> <xsl:template match="section"> <div class="section"> - <h2><xsl:value-of select="title"/></h2> + <h2><xsl:apply-templates select="title"/></h2> <xsl:apply-templates select="(body|subsection)"/> </div> </xsl:template> <xsl:template match="subsection"> <div class="section"> - <h3><xsl:value-of select="title"/></h3> + <h3><xsl:apply-templates select="title"/></h3> <xsl:apply-templates select="(body|subsection)"/> </div> </xsl:template> @@ -395,6 +414,10 @@ </p> </xsl:template> + <xsl:template match="pre"> + <pre><xsl:apply-templates/></pre> + </xsl:template> + <!-- FIXME: Handle lang=... --> <xsl:template match="codesample"> <pre><span class="Constant"> @@ -421,6 +444,7 @@ </div> </xsl:template> + <!-- Lists --> <xsl:template match="li"> <li><xsl:apply-templates/></li> </xsl:template> @@ -433,6 +457,28 @@ <ul><xsl:apply-templates/></ul> </xsl:template> + <!-- Definition Lists --> + <xsl:template match="dl"> + <dl><xsl:apply-templates/></dl> + </xsl:template> + + <xsl:template match="dt"> + <dt><xsl:apply-templates/></dt> + </xsl:template> + + <xsl:template match="dd"> + <dd> + <xsl:for-each select="p"> + <xsl:choose> + <xsl:when test="count(../p) = 1"><xsl:apply-templates/></xsl:when> + <xsl:when test="position() = 1"><p class="first"><xsl:apply-templates/></p></xsl:when> + <xsl:when test="position() = last()"><p class="last"><xsl:apply-templates/></p></xsl:when> + <xsl:otherwise><p><xsl:apply-templates/></p></xsl:otherwise> + </xsl:choose> + </xsl:for-each> + </dd> + </xsl:template> + <xsl:template match="important"> <div class="important"> <p class="first admonition-title">Important</p> @@ -476,7 +522,7 @@ <xsl:template match="/"> <html lang="en-GB" xml:lang="en-GB" xmlns="http://www.w3.org/1999/xhtml"> <head> - <title>Gentoo Development Guide</title> + <title>Gentoo Development Guide: <xsl:value-of select="/guide/chapter[1]/title"/></title> <link rel="stylesheet" href="http://dev.gentoo.org/~plasmaroo/devmanual/styles/devmanual.css" type="text/css" /> </head> <body> @@ -501,7 +547,7 @@ <xsl:apply-templates/> </div> - <div class="navtop" style="text-align: center;"> + <div class="navbottom" style="text-align: center;"> <table style="border-top: 1px dashed #330066; margin-left: auto; margin-right: auto; width: 100%;"> diff --git a/general-concepts/linguas/text.xml b/general-concepts/linguas/text.xml new file mode 100644 index 0000000..d44a879 --- /dev/null +++ b/general-concepts/linguas/text.xml @@ -0,0 +1,13 @@ +<?xml version="1.0"?> +<guide self="general-concepts/linguas/"> +<chapter> +<title>Linguas</title> + +<body> +<todo> +Write this. From vapier: "used to specify languages users wish to have support for. USE=nls covers generally natural language support, but LINGUAS covers specific languages (see the games-rpg/nwn for example). the variable is expanded for USE access in ebuilds. LINGUAS=de would automatically add 'linguas_de' to USE." We also need strip-linguas examples. +</todo> +</body> + +</chapter> +</guide> diff --git a/general-concepts/mirrors/diagram.png b/general-concepts/mirrors/diagram.png Binary files differnew file mode 100644 index 0000000..ede32ea --- /dev/null +++ b/general-concepts/mirrors/diagram.png diff --git a/general-concepts/mirrors/diagram.svg b/general-concepts/mirrors/diagram.svg new file mode 100644 index 0000000..0af1f1c --- /dev/null +++ b/general-concepts/mirrors/diagram.svg @@ -0,0 +1,521 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + sodipodi:docbase="/home/plasmaroo" + sodipodi:docname="diagram.svg" + inkscape:version="0.41" + sodipodi:version="0.32" + version="1.0" + x="0.0000000" + y="0.0000000" + width="700.00000px" + height="250.00000px" + viewBox="0 0 700 250" + id="svg1546"> + <metadata + id="metadata71"> + <rdf:RDF + id="RDF73"> + <cc:Work + id="Work75" + rdf:about=""> + <dc:format + id="format77">image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" + id="type79" /> + </cc:Work> + </rdf:RDF> + </metadata> + <sodipodi:namedview + inkscape:current-layer="svg1546" + inkscape:window-y="264" + inkscape:window-x="164" + inkscape:cy="81.156529" + inkscape:cx="343.48587" + inkscape:zoom="0.97294509" + inkscape:window-height="541" + inkscape:window-width="968" + inkscape:pageshadow="2" + inkscape:pageopacity="1.0000000" + borderopacity="1.0" + bordercolor="#666666" + pagecolor="#eeeeee" + id="base" /> + <defs + id="defs1680" /> + <desc + id="desc1548">CVS to RSYNC Propagation</desc> + <rect + y="0.24284256" + x="-2.0556145" + height="260.03522" + width="710.21484" + id="rect1360" + style="fill:#eeeeee;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="10.000000" + y="110.00000" + style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000" + id="rect1551" /> + <text + x="50" + y="130" + style="text-anchor:middle" + id="text1553">Developers</text> + <line + id="line1555" + stroke="black" + stroke-width="2" + y2="125.00000" + x2="130.00000" + y1="125.00000" + x1="90.000000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1557" + stroke="black" + stroke-width="2" + y2="120.00000" + x2="122.00000" + y1="125.00000" + x1="130.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1559" + stroke="black" + stroke-width="2" + y2="130.00000" + x2="122.00000" + y1="125.00000" + x1="130.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="10.000000" + y="60.000000" + style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000" + id="rect1561" /> + <text + x="50" + y="80" + style="text-anchor:middle" + id="text1563">Developers</text> + <path + d="M 90.000000,75.000000 C 103.33333,75.000000 110.00000,83.333333 110.00000,100.00000 C 110.00000,120.00000 116.66667,128.33333 130.00000,125.00000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1565" /> + <rect + width="80.000000" + height="30.000000" + x="10.000000" + y="160.00000" + style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000" + id="rect1567" /> + <text + x="50" + y="180" + style="text-anchor:middle" + id="text1569">Developers</text> + <path + d="M 90.000000,175.00000 C 103.33333,175.00000 110.00000,166.66667 110.00000,150.00000 C 110.00000,130.00000 116.66667,121.66667 130.00000,125.00000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1571" /> + <rect + width="80.000000" + height="30.000000" + x="130.00000" + y="110.00000" + style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000" + id="rect1573" /> + <text + x="170" + y="130" + style="text-anchor:middle" + id="text1575">dev.gentoo</text> + <line + id="line1577" + stroke="black" + stroke-width="2" + y2="125.00000" + x2="250.00000" + y1="125.00000" + x1="210.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1579" + stroke="black" + stroke-width="2" + y2="120.00000" + x2="242.00000" + y1="125.00000" + x1="250.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1581" + stroke="black" + stroke-width="2" + y2="130.00000" + x2="242.00000" + y1="125.00000" + x1="250.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="250.00000" + y="110.00000" + style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000" + id="rect1583" /> + <text + x="290" + y="123" + style="text-anchor:middle" + id="text1585">Staging</text> + <text + x="290" + y="135" + style="text-anchor:middle" + id="text1587">Box</text> + <line + id="line1589" + stroke="black" + stroke-width="2" + y2="125.00000" + x2="370.00000" + y1="125.00000" + x1="330.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1591" + stroke="black" + stroke-width="2" + y2="120.00000" + x2="362.00000" + y1="125.00000" + x1="370.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1593" + stroke="black" + stroke-width="2" + y2="130.00000" + x2="362.00000" + y1="125.00000" + x1="370.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="370.00000" + y="110.00000" + style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000" + id="rect1595" /> + <text + x="410" + y="130" + style="text-anchor:middle" + id="text1597">OSU Mirrors</text> + <line + id="line1599" + stroke="black" + stroke-width="2" + y2="70.000000" + x2="482.00000" + y1="75.000000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1601" + stroke="black" + stroke-width="2" + y2="80.000000" + x2="482.00000" + y1="75.000000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <path + d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,116.66667 470.00000,100.00000 C 470.00000,80.000000 476.66667,71.666667 490.00000,75.000000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1603" /> + <rect + width="80.000000" + height="30.000000" + x="490.00000" + y="60.000000" + style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000" + id="rect1605" /> + <text + x="530" + y="80" + style="text-anchor:middle" + id="text1607">Public mirror</text> + <line + id="line1609" + stroke="black" + stroke-width="2" + y2="125.00000" + x2="490.00000" + y1="125.00000" + x1="450.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1611" + stroke="black" + stroke-width="2" + y2="120.00000" + x2="482.00000" + y1="125.00000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1613" + stroke="black" + stroke-width="2" + y2="130.00000" + x2="482.00000" + y1="125.00000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="490.00000" + y="110.00000" + style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000" + id="rect1615" /> + <text + x="530" + y="130" + style="text-anchor:middle" + id="text1617">Public mirror</text> + <line + id="line1619" + stroke="black" + stroke-width="2" + y2="170.00000" + x2="482.00000" + y1="175.00000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1621" + stroke="black" + stroke-width="2" + y2="180.00000" + x2="482.00000" + y1="175.00000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <path + d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,133.33333 470.00000,150.00000 C 470.00000,170.00000 476.66667,178.33333 490.00000,175.00000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1623" /> + <rect + width="80.000000" + height="30.000000" + x="490.00000" + y="160.00000" + style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000" + id="rect1625" /> + <text + x="530" + y="180" + style="text-anchor:middle" + id="text1627">Public mirror</text> + <line + id="line1629" + stroke="black" + stroke-width="2" + y2="20.000000" + x2="602.00000" + y1="25.000000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1631" + stroke="black" + stroke-width="2" + y2="30.000000" + x2="602.00000" + y1="25.000000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <path + d="M 570.00000,75.000000 C 583.33333,75.000000 590.00000,66.666667 590.00000,50.000000 C 590.00000,30.000000 596.66667,21.666667 610.00000,25.000000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1633" /> + <rect + width="80.000000" + height="30.000000" + x="610.00000" + y="10.000000" + style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" + id="rect1635" /> + <text + x="650" + y="30" + style="text-anchor:middle" + id="text1637">Users</text> + <line + id="line1639" + stroke="black" + stroke-width="2" + y2="75.000000" + x2="610.00000" + y1="75.000000" + x1="570.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1641" + stroke="black" + stroke-width="2" + y2="70.000000" + x2="602.00000" + y1="75.000000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1643" + stroke="black" + stroke-width="2" + y2="80.000000" + x2="602.00000" + y1="75.000000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="610.00000" + y="60.000000" + style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" + id="rect1645" /> + <text + x="650" + y="80" + style="text-anchor:middle" + id="text1647">Users</text> + <line + id="line1649" + stroke="black" + stroke-width="2" + y2="125.00000" + x2="610.00000" + y1="125.00000" + x1="570.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1651" + stroke="black" + stroke-width="2" + y2="120.00000" + x2="602.00000" + y1="125.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1653" + stroke="black" + stroke-width="2" + y2="130.00000" + x2="602.00000" + y1="125.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="610.00000" + y="110.00000" + style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" + id="rect1655" /> + <text + x="650" + y="130" + style="text-anchor:middle" + id="text1657">Users</text> + <line + id="line1659" + stroke="black" + stroke-width="2" + y2="175.00000" + x2="610.00000" + y1="175.00000" + x1="570.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1661" + stroke="black" + stroke-width="2" + y2="170.00000" + x2="602.00000" + y1="175.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1663" + stroke="black" + stroke-width="2" + y2="180.00000" + x2="602.00000" + y1="175.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="610.00000" + y="160.00000" + style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" + id="rect1665" /> + <text + x="650" + y="180" + style="text-anchor:middle" + id="text1667">Users</text> + <line + id="line1669" + stroke="black" + stroke-width="2" + y2="220.00000" + x2="602.00000" + y1="225.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1671" + stroke="black" + stroke-width="2" + y2="230.00000" + x2="602.00000" + y1="225.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <path + d="M 570.00000,175.00000 C 583.33333,175.00000 590.00000,183.33333 590.00000,200.00000 C 590.00000,220.00000 596.66667,228.33333 610.00000,225.00000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1673" /> + <rect + width="80.000000" + height="30.000000" + x="610.00000" + y="210.00000" + style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" + id="rect1675" /> + <text + x="650" + y="230" + style="text-anchor:middle" + id="text1677">Users</text> +</svg> diff --git a/general-concepts/mirrors/text.xml b/general-concepts/mirrors/text.xml new file mode 100644 index 0000000..8b12bbb --- /dev/null +++ b/general-concepts/mirrors/text.xml @@ -0,0 +1,89 @@ +<?xml version="1.0"?> +<guide self="general-concepts/mirrors/"> +<chapter> +<title>Mirrors</title> + +<section> +<title>Automatic Mirroring</title> + +<body> +<p> +Packages will automatically have their <c>SRC_URI</c> components mirrored onto +Gentoo mirrors. When fetching, portage checks Gentoo mirrors first before +trying the original upstream location. +</p> + +<p> +This is generally desired behaviour -- upstream mirrors are prone to being +rearranged, tidied out or having files modified. +</p> +</body> + +<subsection> +<title>Restricting Automatic Mirroring</title> +<body> +<p> +Three <c>RESTRICT</c> keywords can be used to control the mirroring process. +</p> + +<p> +The <c>RESTRICT="nomirror"</c> setting should be used if we cannot legally mirror +certain files. +</p> + +<p> +The <c>RESTRICT="primaryuri"</c> setting causes portage to try +original locations <e>first</e>, and then fall back to mirrors if necessary -- this +is sometimes useful if approximate download counts are needed, or if upstream +have a reliable mirror setup. +</p> + +<p> +There is also <c>RESTRICT="fetch"</c>, which prevents portage from trying to +fetch anything manually. The `pkg_nofetch`_ 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>Suitable Download Hosts</title> +<body> +<p> +Hosting files off <c>dev.gentoo.org</c> is <b>not</b> acceptable for main-tree items. +Instead, these files must be moved onto <c>mirror://gentoo</c> before release. +</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>. You must ensure that the permissions +are set to <c>ug+rw</c> manually. The file should appear on the mirrors within four +hours (note that this is *less frequent* than `CVS 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. +</p> +</body> +</section> + +<section> +<title>Mirroring Process</title> + +<body> +<figure short="Mirroring Process" link="diagram.png"> +Diagram showing the mirroring process. +</figure> +</body> +</section> + +</chapter> +</guide> diff --git a/general-concepts/overlay/text.xml b/general-concepts/overlay/text.xml new file mode 100644 index 0000000..d3ae6a1 --- /dev/null +++ b/general-concepts/overlay/text.xml @@ -0,0 +1,52 @@ +<?xml version="1.0"?> +<guide self="general-concepts/mirrors/"> +<chapter> +<title>Overlay</title> + +<body> +<p> +Portage can look in multiple places for packages by using an overlay. The +locations of overlays are controlled by the <c>PORTDIR_OVERLAY</c> variable, which +should contain a space-separated list of paths. +</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: +</p> + +<pre> +overlay +|-- dev-util + `-- gengetopt + |-- Manifest + |-- files + | `-- digest-gengetopt-2.13 + `-- gengetopt-2.13.ebuild +</pre> + +<p> +An overlay can be used to 'add' items to the tree (although you must ensure that +<c>/etc/portage/categories</c> is used if any new categories are added) or to +override existing entries. +</p> +</body> + +<section> +<title>Overlay and Eclasses</title> + +<body> +<p> +Be very careful when using eclasses in an overlay. Portage will not do cache +updates when an overlay eclass is changed, nor will it do cache updates when a +main portage tree eclass which is used by an overlay ebuild changes. You may +also encounter bogus 'illegal inherit' notices when working with eclasses in +overlay (see `QA Notice -- ECLASS foo inherited illegally`_). To be safe, +manually <c>touch</c> all relevant overlay files after updating overlay eclasses. +</p> +</body> +</section> + +</chapter> +</guide> diff --git a/general-concepts/pic/text.xml b/general-concepts/pic/text.xml new file mode 100644 index 0000000..2472e5f --- /dev/null +++ b/general-concepts/pic/text.xml @@ -0,0 +1,13 @@ +<?xml version="1.0"?> +<guide self="general-concepts/pic/"> +<chapter> +<title>Linguas</title> + +<body> +<todo> +policy. http://www.gentoo.org/proj/en/hardened/pic-internals.xml has some technical details. +</todo> +</body> + +</chapter> +</guide> diff --git a/general-concepts/portage-cache/text.xml b/general-concepts/portage-cache/text.xml new file mode 100644 index 0000000..73e5622 --- /dev/null +++ b/general-concepts/portage-cache/text.xml @@ -0,0 +1,79 @@ +<?xml version="1.0"?> +<guide self="general-concepts/portage-cache/"> +<chapter> +<title>The Portage Cache</title> + +<body> +<p> +Portage uses a cache for most top-level variables (<c>DEPEND</c>, <c>DESCRIPTION</c>, +<c>SRC_URI</c> and so on). This cache may be generated on a different machine, so +these variables must be either static or generated using only unchanging +'version / name' variables (<c>P</c>, <c>PN</c>, <c>PV</c>, <c>PR</c>, <c>PVR</c> and <c>PF</c>). +</p> + +<p> +So, the following will not work: +</p> + +<codesample lang="ebuild"> +# DO NOT DO THIS! +if ! has_version "x11-libs/gtk+" ; then + DEPEND="${DEPEND} + gtk2? ( >=x11-libs/gtk+-2 ) + !gtk2? ( =x11-libs/gtk+-1.2* )" +fi +</codesample> + +<p> +However, this is legal, since <c>versionator.eclass</c> works upon <c>PV</c>, and +<c>PV</c> and <c>PN</c> are both static: +</p> + +<codesample lang="ebuild"> +inherit versionator + +if [[ $(get_major_version) -ge 7 ]] ; then + IUSE="${IUSE} tcltk mzscheme" + DEPEND="$DEPEND + tcltk? ( dev-lang/tcl ) + mzscheme? ( dev-lisp/mzscheme )" + RDEPEND="$RDEPEND + tcltk? ( dev-lang/tcl ) + mzscheme? ( dev-lisp/mzscheme )" + + if [[ "${MY_PN}" != "vim-core" ]] ; then + RDEPEND="${RDEPEND} !<app-vim/align-30-r1" + fi +fi +</codesample> +</body> + +<section> +<title>Conditional Inherits</title> +<body> +<p> +Because eclasses modify various cached variables, conditional inheritance is not +allowed except where the same results will always be obtained on every system. +For example, inherits based upon <c>USE</c> flags are illegal, but inherits based +solely upon <c>PN</c> are allowed. +</p> + +<p> +As an example of a legal and possibly useful conditional inherit, some eclasses +do: +</p> + +<codesample lang="ebuild"> +if [[ "${PN##*-}" == "cvs" ]] ; then + inherit cvs +fi +</codesample> + +<p> +This allows the same eclass to be used for both regular and <c>-cvs</c> packages. +</p> +</body> +</section> + +</chapter> +</guide> diff --git a/general-concepts/privileges/text.xml b/general-concepts/privileges/text.xml new file mode 100644 index 0000000..8dc516b --- /dev/null +++ b/general-concepts/privileges/text.xml @@ -0,0 +1,15 @@ +<?xml version="1.0"?> +<guide self="general-concepts/privileges/"> +<chapter> +<title>Privileges</title> + +<body> +<todo> +general privs stuff, include stuff on setuid/setgid and sticky since +a lot of people seem to be confused about those... Also notes on the portage +user and group issues, and what we use for root:root to make *bsd work. +</todo> +</body> + +</chapter> +</guide> diff --git a/general-concepts/sandbox/text.xml b/general-concepts/sandbox/text.xml new file mode 100644 index 0000000..d474f26 --- /dev/null +++ b/general-concepts/sandbox/text.xml @@ -0,0 +1,30 @@ +<?xml version="1.0"?> +<guide self="general-concepts/sandbox/"> +<chapter> +<title>Sandbox</title> + +<body> +<p> +During the <c>src_unpack</c>, <c>src_compile</c>, <c>src_test</c> and <c>src_install</c> +phases, <c>ebuild.sh</c> operates inside a <e>sandbox</e>. This is a special environment +which attempts to help prevent badly written ebuilds (or ebuilds working with +badly written build systems) accidentally writing outside of permitted locations. +</p> + +<p> +<b>All packages must build correctly when sandbox is active.</b> Packages must not +achieve this by using sneaky tricks to make sandbox warnings not show up -- the +sandbox is there to ensure that binary packages will work correctly, and that +a badly written <c>Makefile</c> won't cause problems. Using <c>addwrite</c> is +generally <b>not</b> the correct solution. +</p> + +<p> +See `Sandbox Functions Reference`_ for details on sandbox-related functions. See +`Handling Access Violations`_ for suggestions on fixing sandbox-related build +problems. +</p> +</body> + +</chapter> +</guide> diff --git a/general-concepts/slotting/text.xml b/general-concepts/slotting/text.xml new file mode 100644 index 0000000..928f3fd --- /dev/null +++ b/general-concepts/slotting/text.xml @@ -0,0 +1,52 @@ +<?xml version="1.0"?> +<guide self="general-concepts/slotting/"> +<chapter> +<title>Slotting</title> + +<body> +<p> +Packages can support having multiple versions installed simultaneously. This is +useful for libraries which may have changed interfaces between versions -- for +example, the <c>gtk+</c> package can install both versions <c>1.2</c> and <c>2.6</c> in +parallel. This feature is called slotting. +</p> + +<p> +Most packages have no need for slotting. These packages specify <c>SLOT="0"</c> in +the ebuilds. This is <b>not</b> the same as specifying an empty slot -- an empty +slot means "disable slotting entirely", and should not be used. +</p> + +<p> +Portage permits at most one instance of a package installation <e>per <c>SLOT</c> +value</e>. For example, say we have the following: +</p> + +<ul> + <li><c>foo-1.1</c> with <c>SLOT="1"</c></li> + <li><c>foo-1.2</c> with <c>SLOT="1"</c></li> + <li><c>foo-2.0</c> with <c>SLOT="2"</c></li> + <li><c>foo-2.1</c> with <c>SLOT="2"</c></li> +</ul> + +<p> +Then the user could have, say, <c>foo-1.2</c> and <c>foo-2.0</c> installed in +parallel, but <e>not</e> <c>foo-1.1</c> and <c>foo-1.2</c>. Note that it is entirely +possible that the user may have <c>foo-2.0</c> installed and no <c>foo-1.x</c> at all. +</p> + +<p> +It is not possible to <c>DEPEND</c> upon a package in a specific slot. +</p> + +<p> +Currently portage will accept an arbitrary string for the value of <c>SLOT</c>. For +future compatibility, it is recommended that slots contain only characters which +are allowed in an ebuild name or version (alphanumerics, hypens, full stops, +underscores, the plus character) -- other characters may cause problems with +future portage enhancements. +</p> +</body> + +</chapter> +</guide> diff --git a/general-concepts/text.xml b/general-concepts/text.xml index 8df1ded..bc35736 100644 --- a/general-concepts/text.xml +++ b/general-concepts/text.xml @@ -14,4 +14,14 @@ writing ebuilds or working with the portage tree. <include href="autotools/"/> <include href="config-protect/"/> <include href="licenses/"/> +<include href="linguas/"/> +<include href="mirrors/"/> +<include href="overlay/"/> +<include href="portage-cache/"/> +<include href="privileges/"/> +<include href="sandbox/"/> +<include href="slotting/"/> +<include href="tree/"/> +<include href="use-flags/"/> +<include href="user-environment/"/> </guide> diff --git a/general-concepts/tree/text.xml b/general-concepts/tree/text.xml new file mode 100644 index 0000000..1caa834 --- /dev/null +++ b/general-concepts/tree/text.xml @@ -0,0 +1,185 @@ +<?xml version="1.0"?> +<guide self="general-concepts/tree/"> +<chapter> +<title>The Portage Tree</title> + +<body> +<p> +The basic layout of the portage tree is as follows: +</p> + +<ul> + <li> + Categories, for example <c>app-editors</c>, <c>sys-apps</c> + <ul> + <li>Category metadata, for example <c>app-admin/metadata.xml</c></li> + <li> + Package directories for example <c>app-editors/vim</c> + <ul> + <li>Package metadata, for example <c>app-editors/vim/metadata.xml</c></li> + <li>Package changelog, for example <c>app-editors/vim/ChangeLog</c></li> + <li>Package Manifest, for example <c>app-editors/vim/Manifest</c></li> + <li> + Ebuilds, for example <c>app-editors/vim/vim-6.3.068.ebuild</c>, + <c>app-editors/vim/vim-7.0_alpha20050326.ebuild</c> + </li> + <li> + Package files directory, for example <c>app-editors/vim/files</c> + <ul> + <li> + Digest files, for example <c>app-editors/vim/files/digest-vim-6.3.068</c>, + <c>app-editors/vim/files/digest-vim-7.0_alpha20050326</c> + </li> + <li> + Small patches and other miscellaneous files, for example + <c>app-editors/vim/files/vim-completion</c> + </li> + </ul> + </li> + </ul> + </li> + </ul> + </li> + <li>Eclasses directory, <c>eclass/</c></li> + <li>Licenses directory, <c>licenses/</c></li> + <li> + Profiles directory, <c>profiles/</c> + <ul> + <li> + Various control and documentation files, for example <c>categories</c>, + <c>info_pkgs</c>, <c>info_vars</c>, <c>package.mask</c>, <c>use.desc</c> + </li> + <li> + Updates directory, <c>profiles/updates/</c> + <ul> + <li>Updates files, for example <c>profiles/updates/1Q-2005</c></li> + </ul> + </li> + <li> + Main profile cascade + </li> + </ul> + </li> + <li>Scripts directory, <c>scripts/</c></li> + <li> + Distfiles directory, <c>distfiles/</c>. This is not included in the main + CVS tree, but it will be found on most user systems. + </li> + <li> + Packages directory, <c>packages</c>. Again, this is found on user systems but not + in the main CVS tree. + </li> +</ul> +</body> + +<section> +<title>What Belongs in the Tree?</title> +<body> + +<p> +Things that do <b>not</b> belong in the tree: +</p> + +<ul> + <li>Large patches</li> + <li>Non-text files</li> + <li>Photos of teletubbies</li> + <li>Files whose name starts with a dot</li> +</ul> + +<p> +Software-wise, in general all of the following should be met in order for a package to be included in the tree: +</p> + +<dl> +<dt>Active, Cooperative Upstream</dt> +<dd> + <p> + If a package is undeveloped or unmaintained upstream, it can be extremely + difficult to get problems fixed. If a package does not have an active + upstream, the developers who add the package to the tree must ensure that + they are able to fix any issues which may arise. + </p> + <p> + Sometimes upstream may have a reason for not wanting their package included + in the tree. This should be respected. + </p> +</dd> + +<dt>Reasonably Stable</dt> +<dd> + <p> + Keep super-experimental things out of the tree. If you must commit them, + consider using ``package.mask`` until things calm down, or better yet make + them available as overlay ebuilds. + </p> +</dd> + +<dt>Reasonably Useful</dt> +<dd> + <p> + Don't feel obliged to include "Joe's '1337 XMMS Skinz Collection" or "Hans' + Super Cool Fast File System" in the tree just because a few users ask for + it. Stick to things that might actually be of use. + </p> +</dd> + +<dt>Properly Packaged</dt> +<dd> + <p> + If something is only available in live CVS or dodgy autopackage format, + don't include it until upstream can come up with a decent source package. + Similarly, avoid things that don't have a proper build system (where + relevant) -- these are very tricky to maintain. + </p> +</dd> + +<dt>Patching and Distribution Permitted</dt> +<dd> + <p> + If we can't patch packages as necessary ourselves, we end up relying + entirely upon upstream for support. This can be problematic, especially if + upstream are slow at fixing things. We don't want to be in the situation + where we can't stable a critical package because we're still waiting for a + closed-source vendor to get their act together. + </p> + + <p> + Similarly, not being able to mirror and distribute tarballs ourselves makes + us rely entirely upon upstream mirrors. Experience has shown that these are + often extremely unreliable, with files changing, moving or vanishing at + random. + </p> +</dd> + +<dt>Working Ebuilds</dt> +<dd> + <p> + If you don't have a <e>working</e> ebuild, don't include it. + </p> +</dd> + +<dt>Portable</dt> +<dd> + <p> + If software is unportable, it's generally because it's badly written. + Remember that although x86 has a market majority <e>now</e>, it probably won't in + the not too distant future once x86-64 catches on. + </p> +</dd> + +<dt>Reasonable Security Record</dt> +<dd> + <p> + Don't include software that has a terrible security record. Each + vulnerability is a <e>lot</e> of work for a lot of people (security teams, arch + teams and package maintainers). + </p> +</dd> +</dl> + +</body> +</section> + +</chapter> +</guide> diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml new file mode 100644 index 0000000..34ec457 --- /dev/null +++ b/general-concepts/use-flags/text.xml @@ -0,0 +1,230 @@ +<?xml version="1.0"?> +<guide self="general-concepts/use-flags/"> +<chapter> +<title>USE Flags</title> + +<body> +<p> +USE flags are to control optional dependencies and settings which the user may +reasonably want to select. For example, vim can optionally build with support for +the ruby interpreter, and it needs ruby installed to do this -- we use the ruby USE +flag to provide this option. On the other hand, glark requires ruby no matter what, +so no USE flag is used here. +</p> + +<p> +No combination of USE flags should cause a package to fail to build. +</p> + +<p> +Packages should not configure and link based upon what is available at compile time +-- any autodetection must be overridden. +</p> +</body> + +<section> +<title><c>noblah</c> USE Flags</title> +<body> +<p> +If at all possible, avoid <c>noblah</c> style USE flags. These break <c>use.mask</c> +and cause all sorts of complications for arch developers. Here's why: +</p> + +<p> +Consider a hypothetical package named 'vplayer', which plays videos. This +package has optional support, via USE flags, for various sound and video output +methods, various video codecs and so on. +</p> + +<p> +One of vplayer's optional features is support for the 'fakemedia' codec, which +is unfortunately only available as a dodgy x86 binary. We <e>could</e> handle this by +doing something like: +</p> + +<codesample lang="ebuild"> +RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )" +</codesample> + +<p> +Except this is pretty nasty -- what happens when an AMD64 binary is made as +well? Also, users on other archs will see fakemedia listed in <c>emerge -pv</c> +output, even though it is not actually available. +</p> + +<p> +Similarly, say vplayer supports output via the ALSA codec as one option. +However, ALSA isn't (or wasn't when this example was written) available on SPARC +or Alpha. So we could do: +</p> + +<codesample lang="ebuild"> +DEPEND="!sparc? ( !alpha? ( alsa? ( media-libs/alsa-lib ) ) )" +</codesample> + +<p> +Again, it's messy, and ALSA still shows up in the <c>emerge -p</c> output. Also, +once ALSA starts working on SPARC, every ebuild that does this would have to be +manually edited. +</p> + +<p> +The solution is <c>use.mask</c>, which is documented in `Profiles use.mask File`_. +Each profile can have a <c>use.mask</c> file which can be used to forcibly disable +certain USE flags on a given arch (or subarch, or subprofile). So, if the +<c>fakemedia</c> USE flag was use.masked on every non-x86 profile, the following +would be totally legal and wouldn't break anything: +</p> + +<codesample lang="ebuild"> +RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )" +</codesample> + +<p> +Users of non-x86 would see the following when doing <c>emerge -pv vplayer</c>: +</p> + +<pre> +[ebuild R ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz +</pre> + +<p> +To get a flag added to <c>use.mask</c>, ask the relevant arch team. +</p> + +<p> +So what's the problem with <c>noblah</c> flags? +</p> + +<p> +There's no way to forcibly <e>enable</e> a given USE flag on a particular profile. +So, something like: +</p> + +<codesample lang="ebuild"> +RDEPEND="!noalsa? ( media-libs/alsa )" +</codesample> + +<p> +will make your package unusable by archs without ALSA support, and there is no +way to fix it that doesn't involve adding in nasty <c>arch?</c> flags. +</p> + +</body> +</section> + +<section> +<title>Local and Global USE Flags</title> +<body> + +<p> +USE flags are categorised as either local or global. A global USE flag must satisfy several criteria: +</p> + +<ul> + <li>It is used by many different packages.</li> + <li>It has a general non-specific purpose.</li> +</ul> + +<p> +The second point is important. If the effect of the <c>thing</c> USE flag upon +<c>pkg-one</c> is substantially different from the effect it has upon <c>pkg-two</c>, +then <c>thing</c> is not a suitable candidate for being made a global flag. In +particular, note that if <c>client</c> and <c>server</c> USE flags are ever +introduced, they can not be global USE flags for this reason. +</p> + +<p> +Before introducing a new global USE flag, it must be discussed on the gentoo-dev +mailing list. +</p> + +</body> +</section> + +<section> +<title>USE Flag Descriptions</title> +<body> +<p> +All USE flags (excluding <c>USE_EXPAND</c> flags) must be described in either +<c>use.desc</c> or <c>use.local.desc</c> in the <c>profiles/</c> directory. See +`portage-5`_ or the comments in these files for an explanation of the format. +Remember to keep these files sorted. +</p> +</body> +</section> + +<section> +<title>Conflicting USE Flags</title> +<body> +<p> +Occasionally, ebuilds will have conflicting USE flags for functionality. +Checking for them and returning an error is <e>not</e> a viable solution. Instead, +you must pick one of the USE flags in conflict to favour. +</p> + +<p> +One example comes from the <c>msmtp</c> ebuilds. The package can use either SSL +with GnuTLS, SSL with OpenSSL, or no SSL at all. Because GnuTLS is more +featureful than OpenSSL, it is favoured: +</p> + +<codesample lang="ebuild"> +src_compile() { + local myconf + + if use ssl && use gnutls ; then + myconf="${myconf} --enable-ssl --with-ssl=gnutls" + elif use ssl && ! use gnutls ; then + myconf="${myconf} --enable-ssl --with-ssl=openssl" + else + myconf="${myconf} --disable-ssl" + fi + + econf \ + # Other stuff + ${myconf} \ + || die "configure failed" + + emake || die "make failed" +} +</codesample> +</body> +</section> + +<section> +<title>USE_EXPAND and ARCH USE Flags</title> +<body> + +<p> +The <c>VIDEO_CARDS</c>, <c>INPUT_DEVICES</c> and <c>LINGUAS</c> variables are +automatically expanded into USE flags. These are known as <c>USE_EXPAND</c> +variables. If the user has <c>LINGUAS="en fr"</c> in <c>make.conf</c>, for example, +then <c>USE="linguas_en linguas_fr"</c> will automatically be set by portage. +</p> + +<p> +The <c>USE_EXPAND</c> list is set in <c>profiles/base/make.default</c> as of Portage +2.0.51.20. This must not be modified without discussion on the gentoo-dev list, +and it must not be modified in any subprofile. +</p> + +<p> +The current architecture (e.g. <c>x86</c>, <c>sparc</c>, <c>ppc-macos</c>) will +automatically be set as a USE flag as well. See <c>profiles/arch.list</c> for a +full list of valid architecture keywords, and `GLEP 22`_ for an explanation of +the format. +</p> + +<warning> +It is a common misconception that the architecture variable is somehow +related to <c>ACCEPT_KEYWORDS</c>. It isn't. Accepting <c>x86</c> keywords on +<c>sparc</c>, for example, won't set <c>USE="x86"</c>. Similarly, there are no +<c>~arch</c> USE flags, so don't try <c>if use ~x86</c>. +</warning> + +</body> +</section> + +</chapter> +</guide> diff --git a/general-concepts/user-environment/text.xml b/general-concepts/user-environment/text.xml new file mode 100644 index 0000000..d1a5431 --- /dev/null +++ b/general-concepts/user-environment/text.xml @@ -0,0 +1,88 @@ +<?xml version="1.0"?> +<guide self="general-concepts/user-environment/"> +<chapter> +<title>User Environment</title> + +<body> +<p> +User environment variables and <c>make.conf</c> settings get passed on to ebuilds. +This can be useful -- it's how <c>CFLAGS</c> and friends work, for example -- but +it can also result in nasty build-breaking variables like <c>LANG</c> and +<c>LC_ALL</c> getting through. Currently no sanitisation is performed upon the +environment. +</p> +</body> + +<section> +<title>Filtering Variables</title> +<body> +<p> +Certain variables will really really upset certain build systems. A good example +is the locale variables (<c>LC_ALL</c> et al), which if set to certain values will +cause <c>sed</c> or <c>grep</c> expressions involving the likes of <c>[A-Z]</c> to fail. +The easiest thing to do here is to <c>unset</c> or sanitise the offending variables +inside <c>pkg_setup</c>. +</p> + +<p> +The simplest way to unset all locale-related variables is: +</p> + +<codesample lang="ebuild"> +pkg_setup() { + # Unset all locale related variables, they can make the + # build fail. + + eval unset ${!LC_*} LANG +} +</codesample> +</body> +</section> + +<section> +<title>Not Filtering Variables</title> +<body> +<p> +On the other hand, it is extremely important that certain user preferences are +honoured as far as possible. A good example is <c>CFLAGS</c>, which <e>must</e> be +respected (selective filtering is fine, but outright ignoring is not). Ignoring +<c>CFLAGS</c> when compiling can cause serious problems: +</p> + +<ul> +<li> + Ignoring <c>march/mcpu</c> may force kernel or software emulation for certain + opcodes on some architectures. This can be *very* slow -- for example, + <c>openssl</c> built for SPARC v7 but run on v9 is around five times slower for + RSA operations. +</li> + +<li> + Stripping certain ABI-related flags will break linkage. +</li> + +<li> + Stripping certain ABI-related flags will result in invalid code being produced + for certain setups. In extreme cases, we could end up with daft things like + big endian code being produced for little endian CPUs. +</li> + +<li> + If a user's <c>march/mcpu/mtune</c> is ignored, and an auto-detected setting is + used instead, GRP and stages will break. For example, <c>i686</c> stages could no + longer be produced on a <c>pentium-4</c>, and <c>v8</c> stages could no longer be + produced on an <c>UltraSparc</c>. +</li> +</ul> + +<p> +Some packages do this by accident. For example, one might see +<c>CFLAGS=-Wall</c> in <c>Makefile.am</c>. To fix this, either <c>sed</c> in the user's +<c>CFLAGS</c>, or (the better solution) change the variable to <c>AM_CFLAGS</c>, which +will automatically be merged with the user's settings. +</p> +</body> +</section> + +</chapter> +</guide> |
