diff options
Diffstat (limited to 'ebuild-writing/functions')
32 files changed, 1369 insertions, 1166 deletions
diff --git a/ebuild-writing/functions/diagram.svg b/ebuild-writing/functions/diagram.svg index 34ae53b..9547fc7 100644 --- a/ebuild-writing/functions/diagram.svg +++ b/ebuild-writing/functions/diagram.svg @@ -1,318 +1,387 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> <svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" version="1.0" width="1100" height="80" - viewBox="0 100 830 80" + viewBox="-130 100 1100 80" id="svg2503"> + <metadata + id="metadata55"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> <defs id="defs2577" /> <desc id="desc2505">Ebuild Function Order</desc> <rect - width="1100" - height="1000" - x="-135" - y="-10" + width="1101.323" + height="85.745827" + x="-129.33987" + y="96.698219" id="background" - style="fill:#eeeeee" /> - <line - style="stroke:#000000;stroke-width:2.19613099" - id="line2593" - y2="125" - x2="372.11496" - y1="125" - x1="323.88504" /> + style="fill:#eeeeee;stroke-width:0.293003" /> <rect width="80" height="30" - x="-115" - y="110" + x="-7.6246438" + y="115.12637" id="rect2508" - style="fill:#ccccff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="-75.000008" - y="130" + x="32.375347" + y="135.12637" id="text2510" - style="text-anchor:middle">pkg_setup</text> - <g - transform="translate(-125,0)" - id="g2599"> - <line - id="line2512" - y2="125" - x2="130" - y1="125" - x1="90" - style="stroke:#000000;stroke-width:2" /> - <line - id="line2514" - y2="120" - x2="122" - y1="125" - x1="130" - style="stroke:#000000;stroke-width:2" /> - <line - id="line2516" - y2="130" - x2="122" - y1="125" - x1="130" - style="stroke:#000000;stroke-width:2" /> - </g> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_setup</text> <rect width="80" height="30" - x="4.9999924" - y="110" + x="109.90766" + y="115.12637" id="rect2518" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="44.999992" - y="130" + x="149.90767" + y="135.12637" id="text2520" - style="text-anchor:middle">src_unpack</text> - <line - x1="373" - y1="125" - x2="365" - y2="120" - id="line2524" - style="stroke:#000000;stroke-width:2" /> - <line - x1="373" - y1="125" - x2="365" - y2="130" - id="line2526" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_unpack</text> <rect width="80" height="30" - x="373" - y="110" + x="428.4689" + y="115.12637" id="rect2528" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="413" - y="130" + x="468.4689" + y="135.12637" id="text2530" - style="text-anchor:middle">src_compile</text> - <line - x1="453" - y1="125" - x2="493" - y2="125" - id="line2532" - style="stroke:#000000;stroke-width:2" /> - <line - x1="493" - y1="125" - x2="485" - y2="120" - id="line2534" - style="stroke:#000000;stroke-width:2" /> - <line - x1="493" - y1="125" - x2="485" - y2="130" - id="line2536" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_compile</text> <path - d="M 453,125 C 466.33333,125 473,129 473,137 C 473,145.66667 479.66667,150 493,150 L 573,150 C 586.33333,150 593,145.66667 593,137 C 593,129 599.66667,125 613,125" + d="m 509.22566,130.12637 c 11.55683,0 17.33525,4 17.33525,12 0,8.66667 5.77842,13 17.33525,13 h 69.34101 c 11.55683,0 17.33525,-4.33333 17.33525,-13 0,-8 5.77842,-12 17.33525,-12" id="path2538" - style="fill:none;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> <rect width="80" height="30" - x="493" - y="110" + x="538.37067" + y="115.12637" id="rect2540" - style="fill:#ccffcc;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccffcc;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="532.99994" - y="130" + x="578.37061" + y="135.12637" id="text2542" - style="text-anchor:middle">src_test</text> - <line - x1="572.99994" - y1="125" - x2="612.99994" - y2="125" - id="line2544" - style="stroke:#000000;stroke-width:2" /> - <line - x1="612.99994" - y1="125" - x2="604.99994" - y2="120" - id="line2546" - style="stroke:#000000;stroke-width:2" /> - <line - x1="612.99994" - y1="125" - x2="604.99994" - y2="130" - id="line2548" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_test</text> + <g + id="g915"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line2544" + y2="130.12637" + x2="647.90759" + y1="130.12637" + x1="619.22565" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2546" + y2="125.12637" + x2="639.90759" + y1="130.12637" + x1="647.90759" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2548" + y2="135.12637" + x2="639.90759" + y1="130.12637" + x1="647.90759" /> + </g> <rect width="80" height="30" - x="612.99994" - y="110" + x="649.09814" + y="115.12637" id="rect2550" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="652.99994" - y="130" + x="687.09814" + y="135.12637" id="text2552" - style="text-anchor:middle">src_install</text> - <line - x1="692.99994" - y1="125" - x2="732.99994" - y2="125" - id="line2554" - style="stroke:#000000;stroke-width:2" /> - <line - x1="732.99994" - y1="125" - x2="724.99994" - y2="120" - id="line2556" - style="stroke:#000000;stroke-width:2" /> - <line - x1="732.99994" - y1="125" - x2="724.99994" - y2="130" - id="line2558" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_install</text> + <g + id="g920"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line2554" + y2="130.12637" + x2="767.09814" + y1="130.12637" + x1="729.9978" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2556" + y2="125.12637" + x2="759.09814" + y1="130.12637" + x1="767.09814" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2558" + y2="135.12637" + x2="759.09814" + y1="130.12637" + x1="767.09814" /> + </g> <rect width="80" height="30" - x="732.99994" - y="110" + x="767.90759" + y="115.12637" id="rect2560" - style="fill:#ccccff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="772.99994" - y="130" + x="807.90759" + y="135.12637" id="text2562" - style="text-anchor:middle">pkg_preinst</text> - <line - x1="812.99994" - y1="125" - x2="852.99994" - y2="125" - id="line2564" - style="stroke:#000000;stroke-width:2" /> - <line - x1="852.99994" - y1="125" - x2="844.99994" - y2="120" - id="line2566" - style="stroke:#000000;stroke-width:2" /> - <line - x1="852.99994" - y1="125" - x2="844.99994" - y2="130" - id="line2568" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_preinst</text> + <g + id="g925"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line2564" + y2="130.12637" + x2="873.90759" + y1="130.12637" + x1="848.47461" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2566" + y2="125.12637" + x2="865.90759" + y1="130.12637" + x1="873.90759" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2568" + y2="135.12637" + x2="865.90759" + y1="130.12637" + x1="873.90759" /> + </g> <rect width="80" height="30" - x="852.99994" - y="110" + x="873.90759" + y="115.12637" id="rect2570" - style="fill:#ccccff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="892.99994" - y="130" + x="913.90759" + y="135.12637" id="text2572" - style="text-anchor:middle">pkg_postinst</text> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_postinst</text> <path - d="M -34.79404,125.20597 C -15.171638,125.20597 -5.3604277,130.80594 -5.3604277,142.00588 C -5.3604277,153.86465 4.4507723,159.79403 24.073182,159.79403 L 671.61258,159.79403 C 691.23498,159.79403 701.04619,153.86465 701.04619,142.00588 C 701.04619,130.80594 710.85739,125.20597 730.4798,125.20597" + d="m 71.583477,130.33234 c 17.871085,0 26.806636,5.59997 26.806636,16.79991 0,11.85877 8.935547,17.78815 26.806617,17.78815 h 589.74589 c 17.87109,0 26.80666,-5.92938 26.80666,-17.78815 0,-11.19994 8.93553,-16.79991 26.80662,-16.79991" id="path2574" - style="fill:none;stroke:#000000;stroke-width:2.41193652" /> + style="opacity:1;fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> <rect width="80" height="30" - x="245" - y="110" + x="322.2374" + y="115.12637" id="rect2583" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="286.13922" - y="129.99992" + x="363.37662" + y="135.12637" id="text2585" - style="text-anchor:middle">src_configure</text> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_configure</text> <rect width="80" height="30" - x="125" - y="110" + x="215.93536" + y="115.12637" id="rect2587" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="167.51736" - y="129.99992" + x="258.45276" + y="135.12637" id="text2589" - style="text-anchor:middle">src_prepare</text> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_prepare</text> + <rect + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" + id="rect880" + y="115.0796" + x="-113.90761" + height="30" + width="80" /> + <text + x="-73.904678" + y="135.12637" + id="text890" + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_pretend</text> <g - transform="translate(-5.0000077,0)" - id="g2604"> + id="g910"> <line - x1="90" - y1="125" - x2="130" - y2="125" - id="line2606" - style="stroke:#000000;stroke-width:2" /> + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2534" + y2="125.12637" + x2="529.90765" + y1="130.12637" + x1="537.90765" /> <line - x1="130" - y1="125" - x2="122" - y2="120" - id="line2608" - style="stroke:#000000;stroke-width:2" /> + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2536" + y2="135.12637" + x2="529.90765" + y1="130.12637" + x1="537.90765" /> <line - x1="130" - y1="125" - x2="122" - y2="130" - id="line2610" - style="stroke:#000000;stroke-width:2" /> + x1="512.47461" + y1="130.12637" + x2="537.90759" + y2="130.12637" + id="line890" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> + <line + x1="509.22568" + y1="130.12637" + x2="537.90759" + y2="130.12637" + id="line894" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> </g> <g - transform="translate(115,0)" - id="g2612"> + id="g904"> <line - style="stroke:#000000;stroke-width:2" - id="line2614" - y2="125" - x2="130" - y1="125" - x1="90" /> + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2524" + y2="125.12637" + x2="420.4689" + y1="130.12637" + x1="428.4689" /> <line - style="stroke:#000000;stroke-width:2" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2526" + y2="135.12637" + x2="420.4689" + y1="130.12637" + x1="428.4689" /> + <line + x1="403.03592" + y1="130.12637" + x2="428.4689" + y2="130.12637" + id="line902" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> + </g> + <g + id="g899"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" id="line2616" - y2="120" - x2="122" - y1="125" - x1="130" /> + y2="125.12637" + x2="314.2374" + y1="130.12637" + x1="322.2374" /> <line - style="stroke:#000000;stroke-width:2" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" id="line2618" - y2="130" - x2="122" - y1="125" - x1="130" /> + y2="135.12637" + x2="314.2374" + y1="130.12637" + x1="322.2374" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line904" + y2="130.12637" + x2="322.2374" + y1="130.12637" + x1="296.80441" /> + </g> + <g + id="g894"> + <line + x1="215.93535" + y1="130.12637" + x2="207.93535" + y2="125.12637" + id="line2608" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + x1="215.93535" + y1="130.12637" + x2="207.93535" + y2="135.12637" + id="line2610" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + x1="190.50237" + y1="130.12637" + x2="215.93535" + y2="130.12637" + id="line906" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> + </g> + <g + id="g884"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line884" + y2="125.12637" + x2="-15.624653" + y1="130.12637" + x1="-7.6246533" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line886" + y2="135.12637" + x2="-15.624653" + y1="130.12637" + x1="-7.6246533" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line916" + y2="130.12637" + x2="-7.6246533" + y1="130.12637" + x1="-33.057636" /> + </g> + <g + id="g889"> + <line + id="line2514" + y2="125.12637" + x2="101.90767" + y1="130.12637" + x1="109.90767" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + id="line2516" + y2="135.12637" + x2="101.90767" + y1="130.12637" + x1="109.90767" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + x1="72.807327" + y1="130.12637" + x2="109.90767" + y2="130.12637" + id="line920" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> </g> </svg> diff --git a/ebuild-writing/functions/pkg_config/text.xml b/ebuild-writing/functions/pkg_config/text.xml index 422089f..6446777 100644 --- a/ebuild-writing/functions/pkg_config/text.xml +++ b/ebuild-writing/functions/pkg_config/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_config/"> <chapter> <title>pkg_config</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_config</c></title> <body> <codesample lang="ebuild"> -pkg_config() -{ - eerror "This ebuild does not have a config function." +pkg_config() { + eerror "This ebuild does not have a config function." } </codesample> </body> @@ -49,18 +48,18 @@ Taken from the <c>mysql</c> ebuilds. Note the use of <c>${ROOT}</c>. <codesample lang="ebuild"> pkg_config() { - if [ ! -d "${ROOT}"/var/lib/mysql/mysql ] ; then - einfo "Press ENTER to create the mysql database and set proper" - einfo "permissions on it, or Control-C to abort now..." - read - "${ROOT}"/usr/bin/mysql_install_db - else - einfo "Hmm, it appears as though you already have the mysql" - einfo "database in place. If you are having problems trying" - einfo "to start mysqld, perhaps you need to manually run" - einfo "/usr/bin/mysql_install_db and/or check your config" - einfo "file(s) and/or database(s) and/or logfile(s)." - fi + if [[ ! -d ${ROOT}/var/lib/mysql/mysql ]] ; then + einfo "Press ENTER to create the mysql database and set proper" + einfo "permissions on it, or Control-C to abort now..." + read + "${ROOT}"/usr/bin/mysql_install_db + else + einfo "Hmm, it appears as though you already have the mysql" + einfo "database in place. If you are having problems trying" + einfo "to start mysqld, perhaps you need to manually run" + einfo "/usr/bin/mysql_install_db and/or check your config" + einfo "file(s) and/or database(s) and/or logfile(s)." + fi } </codesample> </body> diff --git a/ebuild-writing/functions/pkg_info/text.xml b/ebuild-writing/functions/pkg_info/text.xml index 44f3c77..2e6607b 100644 --- a/ebuild-writing/functions/pkg_info/text.xml +++ b/ebuild-writing/functions/pkg_info/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_info/"> <chapter> <title>pkg_info</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_info</c></title> <body> <codesample lang="ebuild"> -pkg_info() -{ - return +pkg_info() { + return } </codesample> </body> @@ -54,15 +53,19 @@ pkg_info() { <section> <title>Notes on <c>pkg_info</c></title> <body> + +<p> +This phase will be called when a package manager displays information about +a package. +</p> + <p> -this phase will be called when a package manager displays -information about a package. -within EAPI=4, this phase can also be called for non-installed -packages. +The <c>pkg_info</c> function may also be called by the package manager for +non-installed packages. Ebuild writers should note that dependencies may not be +available. </p> + </body> </section> - </chapter> </guide> - diff --git a/ebuild-writing/functions/pkg_nofetch/text.xml b/ebuild-writing/functions/pkg_nofetch/text.xml index f360607..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" - done - return + elog "The following files cannot be fetched for ${PN}:" + local x + for x in ${A}; do + elog " ${x}" + done } </codesample> </body> @@ -51,12 +50,16 @@ pkg_nofetch() <body> <codesample lang="ebuild"> pkg_nofetch() { - einfo "Please download" - einfo " - ${P}-main.tar.bz2" - einfo " - ${P}-extras.tar.bz2" - einfo "from ${HOMEPAGE} and place them in ${DISTDIR}" + einfo "Please download" + einfo " - ${P}-main.tar.bz2" + einfo " - ${P}-extras.tar.bz2" + einfo "from ${HOMEPAGE} and place them in your DISTDIR directory." } </codesample> +<note> +The <c>DISTDIR</c> variable is not valid in <c>pkg_*</c> phases, so it must not +be referenced. +</note> </body> </section> @@ -64,8 +67,8 @@ pkg_nofetch() { <title>Notes on <c>pkg_nofetch</c></title> <body> <p> -This function is only triggered for packages which -have <c>RESTRICT="fetch"</c> (see <uri link="::general-concepts/mirrors#Restricting Automatic Mirroring"/>) +This function is only triggered for packages which have <c>RESTRICT="fetch"</c> +(see <uri link="::general-concepts/mirrors/#Restricting automatic mirroring"/>) set, and only if one or more components listed in <c>SRC_URI</c> are not already available in the <c>distfiles</c> directory. </p> diff --git a/ebuild-writing/functions/pkg_postinst/text.xml b/ebuild-writing/functions/pkg_postinst/text.xml index 8b86c4c..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,9 +32,8 @@ <title>Default <c>pkg_postinst</c></title> <body> <codesample lang="ebuild"> -pkg_postinst() -{ - return +pkg_postinst() { + return } </codesample> </body> @@ -45,21 +44,21 @@ pkg_postinst() <body> <codesample lang="ebuild"> pkg_postinst() { - if $OLD_FLUXBOX_VERSION ; then - ewarn "You must restart fluxbox before using the [include] /directory/" - ewarn "feature if you are upgrading from an older fluxbox!" - ewarn " " - fi - elog "If you experience font problems, or if fluxbox takes a very" - elog "long time to start up, please try the 'disablexmb' USE flag." - elog "If that fails, please report bugs upstream." + if ${OLD_FLUXBOX_VERSION} ; then + ewarn "You must restart fluxbox before using the [include] /directory/" + ewarn "feature if you are upgrading from an older fluxbox!" + ewarn " " + fi + elog "If you experience font problems, or if fluxbox takes a very" + elog "long time to start up, please try the 'disablexmb' USE flag." + elog "If that fails, please report bugs upstream." } </codesample> </body> </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 fa2a21d..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,9 +32,8 @@ <title>Default <c>pkg_postrm</c></title> <body> <codesample lang="ebuild"> -pkg_postrm() -{ - return +pkg_postrm() { + return } </codesample> </body> @@ -44,15 +43,18 @@ pkg_postrm() <title>Sample <c>pkg_postrm</c></title> <body> <codesample lang="ebuild"> +inherit xdg-utils + pkg_postrm() { - fdo-mime_mime_database_update + xdg_desktop_database_update + xdg_mimeinfo_database_update } </codesample> </body> </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 9cdeb4a..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,9 +32,8 @@ <title>Default <c>pkg_preinst</c></title> <body> <codesample lang="ebuild"> -pkg_preinst() -{ - return +pkg_preinst() { + return } </codesample> </body> @@ -45,15 +44,15 @@ pkg_preinst() <body> <codesample lang="ebuild"> pkg_preinst() { - enewgroup foo - enewuser foo -1 /bin/false /dev/null foo + enewgroup foo + enewuser foo -1 /bin/false /dev/null foo } </codesample> </body> </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 d9f8a6f..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,9 +32,8 @@ <title>Default <c>pkg_prerm</c></title> <body> <codesample lang="ebuild"> -pkg_prerm() -{ - return +pkg_prerm() { + return } </codesample> </body> @@ -45,15 +44,15 @@ pkg_prerm() <body> <codesample lang="ebuild"> pkg_prerm() { - # clean up temp files - [[ -d "${ROOT}/var/tmp/foo" ]] && rm -rf "${ROOT}/var/tmp/foo" + # clean up temp files + [[ -d "${ROOT}/var/tmp/foo" ]] && rm -rf "${ROOT}/var/tmp/foo" } </codesample> </body> </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 0279145..a838757 100644 --- a/ebuild-writing/functions/pkg_pretend/text.xml +++ b/ebuild-writing/functions/pkg_pretend/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_pretend/"> <chapter> <title>pkg_pretend</title> @@ -23,11 +23,11 @@ </tr> <tr> <th>Called for</th> - <ti>ebuild</ti> + <ti>ebuild, binary</ti> </tr> <tr> <th>EAPI</th> - <ti>3</ti> + <ti>4</ti> </tr> </table> </body> @@ -36,9 +36,8 @@ <title>Default <c>pkg_pretend</c></title> <body> <codesample lang="ebuild"> -pkg_pretend() -{ - return +pkg_pretend() { + return } </codesample> </body> @@ -67,12 +66,13 @@ pkg_pretend() { <title>Notes on <c>pkg_pretend</c></title> <body> <p> -the <c>pkg_pretend</c> phase can be used to do sanity checks +The <c>pkg_pretend</c> phase can be used to do sanity checks before the main phase function sequence is run (meaning this phase is executed after the package manager has calculated the dependencies and before installing them). This phase typically checks for a kernel configuration and may <c>eerror</c> and <c>die</c> when needed. +</p> <important> There is no guarantee that the ebuild's dependencies are installed when this phase is called. @@ -81,7 +81,6 @@ This phase typically checks for a kernel configuration and may As <c>pkg_pretend</c> is not called in the main phase function sequence, environment saving is not guaranteed. </important> -</p> </body> </section> diff --git a/ebuild-writing/functions/pkg_setup/text.xml b/ebuild-writing/functions/pkg_setup/text.xml index a7fe9d2..90f89cf 100644 --- a/ebuild-writing/functions/pkg_setup/text.xml +++ b/ebuild-writing/functions/pkg_setup/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_setup/"> <chapter> <title>pkg_setup</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_setup</c></title> <body> <codesample lang="ebuild"> -pkg_setup() -{ - return +pkg_setup() { + return } </codesample> </body> @@ -45,19 +44,19 @@ pkg_setup() <body> <codesample lang="ebuild"> pkg_setup() { - # We need to know which GUI we're building in several - # different places, so work it out here. - if use gtk ; then - if use gtk2 ; then - export mypkg_gui="gtk2" - else - export mypkg_gui="gtk1" - fi - elif use motif then - export mypkg_gui="motif" - else - export mypkg_gui="athena" - fi + # We need to know which GUI we're building in several + # different places, so work it out here. + if use gtk ; then + if use gtk2 ; then + export mypkg_gui="gtk2" + else + export mypkg_gui="gtk1" + fi + elif use motif then + export mypkg_gui="motif" + else + export mypkg_gui="athena" + fi } </codesample> </body> diff --git a/ebuild-writing/functions/src_compile/build-environment/text.xml b/ebuild-writing/functions/src_compile/build-environment/text.xml index 8c16587..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> @@ -17,13 +17,13 @@ Except where otherwise specified, any function which operates on </note> <p> -Ebuilds must not simply ignore user CFLAGS, CXXFLAGS or LDFLAGS<d/> see -<uri link="::general-concepts/user-environment#Not Filtering Variables"/>. +Ebuilds must not simply ignore user CFLAGS, CXXFLAGS or LDFLAGS <d/> see +<uri link="::general-concepts/user-environment/#Not filtering variables"/>. </p> </body> <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> @@ -69,9 +69,9 @@ remove. </p> <codesample lang="ebuild"> - # -fomit-frame-pointer leads to nasty broken code on sparc thanks to a - # rather icky asm function - use sparc && filter-flags -fomit-frame-pointer + # -fomit-frame-pointer leads to nasty broken code on sparc thanks to a + # rather icky asm function + use sparc && filter-flags -fomit-frame-pointer </codesample> <p> @@ -86,15 +86,15 @@ conservative set of flags. </p> <codesample lang="ebuild"> - # Our app hates screwy flags - strip-flags + # Our app hates screwy flags + strip-flags </codesample> </body> </section> <section> -<title>Flag Replacement</title> +<title>Flag replacement</title> <body> <p> @@ -104,8 +104,8 @@ is most commonly used to replace <c>-Os</c> with <c>-O2</c> </p> <codesample lang="ebuild"> - # Seems to have issues with -Os, switch to -O2 - replace-flags -Os -O2 + # Seems to have issues with -Os, switch to -O2 + replace-flags -Os -O2 </codesample> <p> @@ -116,15 +116,15 @@ the flags to be replaced. </p> <codesample lang="ebuild"> - # Can't use ultrasparc or ultrasparc3 code, drop to v9 - replace-cpu-flags ultrasparc ultrasparc3 v9 + # Can't use ultrasparc or ultrasparc3 code, drop to v9 + replace-cpu-flags ultrasparc ultrasparc3 v9 </codesample> </body> </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> @@ -133,15 +133,15 @@ functions can be used here. </p> <codesample lang="ebuild"> - # If we're using selinux, we need to add a -D - use selinux && append-flags "-DWITH_SELINUX" + # If we're using selinux, we need to add a -D + use selinux && append-flags "-DWITH_SELINUX" - # Secure linking needed, since we're setuid root - append-ldflags -Wl,-z,now + # Secure linking needed, since we're setuid root + append-ldflags -Wl,-z,now </codesample> <p> -See <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic.eclass</uri> for a full reference. +See <uri link="::eclass-reference/flag-o-matic.eclass/"/> for a full reference. </p> </body> </section> diff --git a/ebuild-writing/functions/src_compile/building/text.xml b/ebuild-writing/functions/src_compile/building/text.xml index bed3dd7..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,22 +20,32 @@ 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> Sometimes a package will try to use a bizarre compiler, or will need to be told which compiler to use. In these situations, the <c>tc-getCC()</c> function from -<uri link="::eclass-reference/toolchain-funcs.eclass/">toolchain-funcs.eclass</uri> should be used. Other similar functions are available -<d/> these are documented in <c>man toolchain-funcs.eclass</c>. +<uri link="::eclass-reference/toolchain-funcs.eclass/"/> should be used. +Other similar functions are available <d/> these are documented in +<c>man toolchain-funcs.eclass</c>. +</p> + +<p> +Note that packages should always respect the user's <c>CC</c> preference +and must not rely on convenience symlinks such as <c>/usr/bin/cc</c> +or <c>/usr/bin/gcc</c>. A tracker <uri link="https://bugs.gentoo.org/243502"> +bug</uri> exists to document such issues. Additional documentation exists on the +<uri link="https://wiki.gentoo.org/wiki/Project:Toolchain/use_native_symlinks"> +wiki</uri>. </p> <note> @@ -46,27 +56,39 @@ It is <e>not</e> correct to use the <c>${CC}</c> variable for this purpose. Sometimes a package will not use the user's <c>${CFLAGS}</c> or <c>${LDFLAGS}</c>. This must be worked around, as sometimes these variables are used for specifying critical ABI options. In these cases, the build scripts should be modified (for -example, with <c>sed</c>) to use <c>${CFLAGS}</c> or <c>${LDFLAGS}</c> correctly. +example, with <c>sed</c> or via a patch) to use <c>${CFLAGS}</c> or +<c>${LDFLAGS}</c> correctly. </p> <codesample lang="ebuild"> inherit flag-o-matic toolchain-funcs +src_prepare() { + default + + # We have a weird Makefile to work with which ignores our + # compiler preferences. yay! + # Note the single quotes (hence the delimiter is not an issue) + sed -i -e 's:cc -O2:$(CC) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS):' Makefile \ + || die "sed fix failed. Uh-oh..." +} + src_compile() { - # -Os not happy - replace-flags -Os -O2 - - # We have a weird build.sh to work with which ignores our - # compiler preferences. yay! - sed -i -e "s:cc -O2:$(tc-getCC) ${CFLAGS} ${LDFLAGS}:" build.sh \ - || die "sed fix failed. Uh-oh..." - ./build.sh || die "Build failed!" + # -Os not happy + replace-flags -Os -O2 + + emake CC="$(tc-getCC)" \ + CPPFLAGS="${CPPFLAGS}" \ + CFLAGS="${CFLAGS}" \ + LDFLAGS="${LDFLAGS}" } </codesample> <note> -When using <c>sed</c> with <c>CFLAGS</c> or <c>LDFLAGS</c>, it is not safe to use -a comma or a slash as a delimiter. The recommended character is a colon. +Try to not substitute the value with <c>sed</c> directly, but instead make the +build script use the variables. The variables may contain characters such as a +slash, a comma, or a colon, which are often used with <c>sed</c>, and this +would break its syntax. </note> <p> diff --git a/ebuild-writing/functions/src_compile/no-build-system/text.xml b/ebuild-writing/functions/src_compile/no-build-system/text.xml index 99b873a..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> @@ -14,7 +14,7 @@ Here's an example, from <c>app-misc/hilite</c>: <codesample lang="ebuild"> src_compile() { - $(tc-getCC) ${LDFLAGS} ${CFLAGS} -o ${PN} ${P}.c || die + $(tc-getCC) ${CFLAGS} ${CPPFLAGS} ${LDFLAGS} -o ${PN} ${P}.c || die } </codesample> @@ -25,29 +25,29 @@ broken build system that doesn't actually work: <codesample lang="ebuild"> src_compile() { - local x - for x in asclock parser symbols config - do - $(tc-getCC) \ - ${CPPFLAGS} ${CFLAGS} ${ASFLAGS} \ - -I/usr/include \ - -Dlinux \ - -D_POSIX_C_SOURCE=199309L \ - -D_POSIX_SOURCE \ - -D_XOPEN_SOURCE \ - -D_BSD_SOURCE \ - -D_SVID_SOURCE \ - -DFUNCPROTO=15 \ - -DNARROWPROTO \ - -c -o ${x}.o ${x}.c || die "compile asclock failed" - done - $(tc-getCC) \ - ${LDFLAGS} \ - -o asclock \ - asclock.o parser.o symbols.o config.o \ - -L/usr/lib \ - -L/usr/lib/X11 \ - -lXpm -lXext -lX11 || die "link asclock failed" + local x + for x in asclock parser symbols config + do + $(tc-getCC) \ + ${CPPFLAGS} ${CFLAGS} ${ASFLAGS} \ + -I"${EPREFIX}"/usr/include \ + -Dlinux \ + -D_POSIX_C_SOURCE=199309L \ + -D_POSIX_SOURCE \ + -D_XOPEN_SOURCE \ + -D_BSD_SOURCE \ + -D_SVID_SOURCE \ + -DFUNCPROTO=15 \ + -DNARROWPROTO \ + -c -o ${x}.o ${x}.c || die "compile asclock failed" + done + $(tc-getCC) \ + ${LDFLAGS} \ + -o asclock \ + asclock.o parser.o symbols.o config.o \ + -L"${EPREFIX}"/usr/lib \ + -L"${EPREFIX}"/usr/lib/X11 \ + -lXpm -lXext -lX11 || die "link asclock failed" } </codesample> diff --git a/ebuild-writing/functions/src_compile/text.xml b/ebuild-writing/functions/src_compile/text.xml index 89350cb..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> @@ -11,7 +11,7 @@ </tr> <tr> <th>Purpose</th> - <ti>Configure and build the package.<important>the configure parts of <c>src_compile</c> have been splitted out in EAPI=2 to <c>src_configure</c>. see <uri link="::ebuild-writing/functions/src_configure"/></important></ti> + <ti>Build the package.</ti> </tr> <tr> <th>Sandbox</th> @@ -30,75 +30,49 @@ <section> <title>Default <c>src_compile</c></title> + <body> -<subsection> -<title>with EAPI=0,1</title> -<body> -<codesample lang="ebuild"> -src_compile() { - if [ -x ./configure ]; then - econf - fi - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then - emake || die "emake failed" - fi -} -</codesample> -</body> -</subsection> -<subsection> -<title>with EAPI=2</title> -<body> +<ul> + <li> <codesample lang="ebuild"> src_compile() { - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then - emake || die "emake failed" - fi + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then + emake || die "emake failed" + fi } </codesample> -</body> -</subsection> + </li> +</ul> </body> </section> <section> <title>Sample <c>src_compile</c></title> <body> -<subsection> -<title>with EAPI=0</title> -<body> + +<ul> + <li> <codesample lang="ebuild"> src_compile() { - use sparc && filter-flags -fomit-frame-pointer - append-ldflags -Wl,-z,now - - econf \ - $(use_enable ssl ) \ - $(use_enable perl perlinterp ) + use sparc && filter-flags -fomit-frame-pointer + append-ldflags -Wl,-z,now - emake || die "Make failed!" + emake } </codesample> -<note> -You also need to inherit the <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> eclass in order to use the <c>append-ldflags</c> function. -</note> -</body> -</subsection> -<subsection> -<title>with EAPI=2</title> -<body> -<p> -porting the above example to EAPI=2, you won't need to define an extra -<c>src_compile</c>, as it only calls <c>emake</c> (which is the default -<c>src_compile</c> function). -</p> -</body> -</subsection> + <note> + You also need to inherit the + <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> + eclass in order to use the <c>append-ldflags</c> function. + </note> + </li> +</ul> + </body> </section> <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 @@ -112,7 +86,6 @@ The following subsections cover different topics which often occur when writing </chapter> <include href="build-environment/"/> -<!--<include href="configuring/"/>--> <include href="building/"/> <include href="no-build-system/"/> </guide> diff --git a/ebuild-writing/functions/src_configure/configuring/text.xml b/ebuild-writing/functions/src_configure/configuring/text.xml index 677334e..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> @@ -30,18 +30,18 @@ where appropriate, be used to generate these switches. <codesample lang="ebuild"> src_configure() { - # We have optional perl, python and ruby support - econf \ - $(use_enable perl ) \ - $(use_enable python ) \ - $(use_enable ruby ) + # We have optional perl, python and ruby support + econf \ + $(use_enable perl) \ + $(use_enable python) \ + $(use_enable ruby) } src_configure() { - # Our package optional IPv6 support which uses --with rather than - # --enable / --disable + # Our package optional IPv6 support which uses --with rather than + # --enable / --disable - econf $(use_with ipv6 ) + econf $(use_with ipv6) } </codesample> @@ -54,17 +54,17 @@ argument forms: <codesample lang="ebuild"> src_configure() { - # Our package has optional perl, python and ruby support - econf \ - $(use_enable perl perlinterp ) \ - $(use_enable python pythoninterp ) \ - $(use_enable ruby rubyinterp ) + # Our package has optional perl, python and ruby support + econf \ + $(use_enable perl perlinterp) \ + $(use_enable python pythoninterp) \ + $(use_enable ruby rubyinterp) - # ... + # ... } -src_compile() { - econf $(use_with X x11 ) +src_configure() { + econf $(use_with X x11) } </codesample> @@ -74,5 +74,56 @@ form can be used. </p> </body> +<section> +<title><c>econf</c> options</title> +<body> + +<p> +<c>econf</c> is designed to work with configure scripts generated by +GNU Autoconf. It first passes the default options listed below to the configure +script, followed by any additional parameters passed to <c>econf</c>. +</p> + +<ul> + <li><c>--prefix="${EPREFIX}"/usr</c></li> + <li><c>--mandir="${EPREFIX}"/usr/share/man</c></li> + <li><c>--infodir="${EPREFIX}"/usr/share/info</c></li> + <li><c>--datadir="${EPREFIX}"/usr/share</c></li> + <li><c>--sysconfdir="${EPREFIX}"/etc</c></li> + <li><c>--localstatedir="${EPREFIX}"/var/lib</c></li> + <li> + <c>--build="${CBUILD}"</c> (only passed if <c>CBUILD</c> is non-empty) + </li> + <li><c>--host="${CHOST}"</c></li> + <li> + <c>--target="${CTARGET}"</c> (only passed if <c>CTARGET</c> is non-empty) + </li> + <li> + <c>--libdir</c> is set from the value of the <c>LIBDIR_${ABI}</c> variable + in profiles. + </li> + <li><c>--disable-dependency-tracking</c></li> + <li><c>--disable-silent-rules</c></li> +</ul> + +<p> +In EAPI 6 and later, the following options are passed in addition: +</p> + +<ul> + <li><c>--docdir="${EPREFIX}"/usr/share/doc/${PF}</c></li> + <li><c>--htmldir="${EPREFIX}"/usr/share/doc/${PF}/html</c></li> +</ul> + +<p> +In EAPI 7 and later, the following option is passed in addition: +</p> + +<ul> + <li><c>--with-sysroot="${ESYSROOT:-/}"</c></li> +</ul> + +</body> +</section> </chapter> </guide> diff --git a/ebuild-writing/functions/src_configure/text.xml b/ebuild-writing/functions/src_configure/text.xml index 0740309..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> @@ -38,8 +38,8 @@ <codesample lang="ebuild"> src_configure() { if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then - econf - fi + econf + fi } </codesample> </body> @@ -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 + use sparc && filter-flags -fomit-frame-pointer + append-ldflags -Wl,-z,now - econf \ - $(use_enable ssl ) \ - $(use_enable perl perlinterp ) + econf \ + $(use_enable ssl) \ + $(use_enable perl perlinterp) } </codesample> + +<note> +You also need to inherit the +<uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> +eclass in order to use the <c>append-ldflags</c> function. +</note> + </body> </section> <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 @@ -76,8 +85,5 @@ The following subsections cover different topics which often occur when writing </chapter> <include href="configuring/"/> -<!--<include href="build-environment/"/> -<include href="building/"/> -<include href="no-build-system/"/>--> </guide> diff --git a/ebuild-writing/functions/src_install/docompress/text.xml b/ebuild-writing/functions/src_install/docompress/text.xml new file mode 100644 index 0000000..adaef2b --- /dev/null +++ b/ebuild-writing/functions/src_install/docompress/text.xml @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-writing/functions/src_install/docompress/"> +<chapter> +<title>Controllable compression</title> +<body> + +<p> +You can call the <c>docompress</c> function in <c>src_install</c> to control +which items in the destination folder <c>${D}</c> should be compressed and +which shouldn't be compressed. You can include or exclude directories or plain +files. The default inclusion list contains: +</p> + +<ul> + <li><c>/usr/share/doc</c></li> + <li><c>/usr/share/info</c></li> + <li><c>/usr/share/man</c></li> +</ul> + +<p> +The default exclusion list contains: +</p> + +<ul> + <li><c>/usr/share/doc/${PF}/html</c></li> +</ul> + +<p> +When a directory is in- or excluded, all files and directories in the given +directories shall be added to the corresponding list. If a file is in- or +excluded, the file shall be added to the corresponding list (exclusion is +stronger than inclusion <d/> if a file is in both lists, the inclusion will +be ignored). +</p> + +<p> +If the first argument of <c>docompress</c> is <c>-x</c>, the items specified +will be added to the exclusion list, otherwise they will be added to the +inclusion list. +</p> + +<note> +When <c>docompress</c> is called, it is <e>not</e> required that the paths +specified as its arguments are pointing to existing files or directories. +However, if a file still doesn't exist when <c>src_install</c> has completed, +it will be ignored with a warning. +</note> + +</body> +</chapter> +</guide> diff --git a/ebuild-writing/functions/src_install/text.xml b/ebuild-writing/functions/src_install/text.xml index 530baf1..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> @@ -31,39 +31,41 @@ <section> <title>Default <c>src_install</c></title> <body> -<p> -For EAPIs 0,1,2, and 3, the default <c>src_install</c> function is the -following: -</p> -<codesample lang="ebuild"> -src_install() -{ - return -} -</codesample> + <p> For EAPIs 4 and later, the default <c>src_install</c> function is the following: </p> <codesample lang="ebuild"> src_install() { - if [[ -f Makefile ]] || [[ -f GNUmakefile]] || [[ -f makefile ]] ; then + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]] ; then emake DESTDIR="${D}" install fi - if ! declare -p DOCS >/dev/null 2>&1 ; then + if ! declare -p DOCS >/dev/null 2>&1 ; then local d for d in README* ChangeLog AUTHORS NEWS TODO CHANGES THANKS BUGS \ FAQ CREDITS CHANGELOG ; do [[ -s "${d}" ]] && dodoc "${d}" done - elif declare -p DOCS | grep -q "^declare -a " ; then + elif [[ $(declare -p DOCS) == "declare -a"* ]] ; then dodoc "${DOCS[@]}" else dodoc ${DOCS} fi } </codesample> -<important>The following examples assume EAPI 4 or later</important> +<p> +For EAPIs 6 and later, the default <c>src_install</c> function is the following: +</p> +<codesample lang="ebuild"> +src_install() { + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]] ; then + emake DESTDIR="${D}" install + fi + einstalldocs +} +</codesample> + </body> </section> @@ -73,8 +75,8 @@ src_install() { <codesample lang="ebuild"> src_install() { - emake DESTDIR="${D}" install - dodoc README CHANGES + emake DESTDIR="${D}" install + dodoc README CHANGES } </codesample> @@ -82,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> @@ -91,7 +93,7 @@ install to a non-root location. If possible, this should be used: </p> <codesample lang="ebuild"> - emake DESTDIR="${D}" install + emake DESTDIR="${D}" install </codesample> <note> @@ -101,30 +103,33 @@ if you hit an error. </note> <p> - Sometimes this will end up installing a few things into strange - places. If and only if this is the case, the <c>einstall</c> - function can be used. It is usually necessary to include additional - <c>dodoc</c> statements for the <c>README</c>, <c>ChangeLog</c>, etc - in these cases: +Usually the package's build system will not install the <c>README</c>, +<c>ChangeLog</c>, etc. files, so it is necessary to include additional +<c>dodoc</c> statements for them: </p> <codesample lang="ebuild"> - einstall - dodoc README CHANGES + emake DESTDIR="${D}" install + dodoc README CHANGES + dodoc -r doc </codesample> +<p> +<c>dodoc</c> supports <c>-r</c> as the first argument, which allows directories +to be installed recursively. +</p> + <note> -There is no need to <c>dodoc</c> <c>COPYING</c>! The license belongs -to <c>${PORTDIR}/licenses</c>. Sometimes though, you might want to -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> @@ -135,64 +140,64 @@ compilation required) themes: </p> <codesample lang="ebuild"> - dodir /usr/share/foo-styles/ - cp -R "${S}/" "${D}/" || die "Install failed!" + dodir /usr/share/foo-styles/ + cp -R "${S}/" "${D}/" || die "Install failed!" </codesample> <p> Or sometimes a combination of <c>insinto</c> and <c>doins</c> (plus related -functions -- see <uri link="::function-reference/install-functions"/>) <d/> the following is based -upon the <c>sys-fs/udev</c> install: +functions <d/> see <uri link="::function-reference/install-functions/"/>) <d/> +the following is based upon the <c>sys-fs/udev</c> install: </p> <codesample lang="ebuild"> src_install() { - dobin udevinfo - dobin udevtest - into / - dosbin udev - dosbin udevd - dosbin udevsend - dosbin udevstart - dosbin extras/scsi_id/scsi_id - dosbin extras/volume_id/udev_volume_id - - exeinto /etc/udev/scripts - doexe extras/ide-devfs.sh - doexe extras/scsi-devfs.sh - doexe extras/cdsymlinks.sh - doexe extras/dvb.sh - - insinto /etc/udev - newins "${FILESDIR}/udev.conf.post_050" udev.conf - doins extras/cdsymlinks.conf - - # For devfs style layout - insinto /etc/udev/rules.d/ - newins etc/udev/gentoo/udev.rules 50-udev.rules - - # scsi_id configuration - insinto /etc - doins extras/scsi_id/scsi_id.config - - # set up symlinks in /etc/hotplug.d/default - dodir /etc/hotplug.d/default - dosym ../../../sbin/udevsend /etc/hotplug.d/default/10-udev.hotplug - - # set up the /etc/dev.d directory tree - dodir /etc/dev.d/default - dodir /etc/dev.d/net - exeinto /etc/dev.d/net - doexe etc/dev.d/net/hotplug.dev - - doman *.8 - doman extras/scsi_id/scsi_id.8 - - dodoc ChangeLog FAQ HOWTO-udev_for_dev README TODO - dodoc docs/{overview,udev-OLS2003.pdf,udev_vs_devfs,RFC-dev.d,libsysfs.txt} - dodoc docs/persistent_naming/* docs/writing_udev_rules/* - - newdoc extras/volume_id/README README_volume_id + dobin udevinfo + dobin udevtest + into / + dosbin udev + dosbin udevd + dosbin udevsend + dosbin udevstart + dosbin extras/scsi_id/scsi_id + dosbin extras/volume_id/udev_volume_id + + exeinto /etc/udev/scripts + doexe extras/ide-devfs.sh + doexe extras/scsi-devfs.sh + doexe extras/cdsymlinks.sh + doexe extras/dvb.sh + + insinto /etc/udev + newins "${FILESDIR}/udev.conf.post_050" udev.conf + doins extras/cdsymlinks.conf + + # For devfs style layout + insinto /etc/udev/rules.d/ + newins etc/udev/gentoo/udev.rules 50-udev.rules + + # scsi_id configuration + insinto /etc + doins extras/scsi_id/scsi_id.config + + # set up symlinks in /etc/hotplug.d/default + dodir /etc/hotplug.d/default + dosym ../../../sbin/udevsend /etc/hotplug.d/default/10-udev.hotplug + + # set up the /etc/dev.d directory tree + dodir /etc/dev.d/default + dodir /etc/dev.d/net + exeinto /etc/dev.d/net + doexe etc/dev.d/net/hotplug.dev + + doman *.8 + doman extras/scsi_id/scsi_id.8 + + dodoc ChangeLog FAQ HOWTO-udev_for_dev README TODO + dodoc docs/{overview,udev-OLS2003.pdf,udev_vs_devfs,RFC-dev.d,libsysfs.txt} + dodoc docs/persistent_naming/* docs/writing_udev_rules/* + + newdoc extras/volume_id/README README_volume_id } </codesample> @@ -204,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 @@ -215,5 +220,20 @@ upstream explaining the situation to them. </body> </section> +<section> +<title><c>src_install</c> processes</title> +<body> + +<p> +The following subsections cover different topics which often occur when writing +<c>src_install</c> functions. +</p> + +<contentsTree/> + +</body> +</section> </chapter> + +<include href="docompress/"/> </guide> diff --git a/ebuild-writing/functions/src_prepare/autopackage/text.xml b/ebuild-writing/functions/src_prepare/autopackage/text.xml index 56c6b47..42fb255 100644 --- a/ebuild-writing/functions/src_prepare/autopackage/text.xml +++ b/ebuild-writing/functions/src_prepare/autopackage/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_prepare/autopackage/"> <chapter> <title>Autopackage</title> diff --git a/ebuild-writing/functions/src_prepare/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 1322a5e..0000000 --- a/ebuild-writing/functions/src_prepare/epatch/text.xml +++ /dev/null @@ -1,155 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_prepare/epatch/"> -<chapter> -<title>Patching with epatch</title> - -<body> -<p> -The canonical way of applying patches in ebuilds is to -use <c>epatch</c> (from <c>eutils.eclass</c>, which you must make sure -to import!) inside <c>src_prepare</c>. This function automatically -handles <c>-p</c> levels, <c>gunzip</c> and so on as necessary. Also note that olds ebuild may still use src_unpack to apply patches. This is because those ebuilds are based in EAPI="1". You are advised to use EAPI="2" and apply your patches in src_prepare function instead. -</p> - -<p> -Note that distributing modified tarballs rather than a vanilla tarball -and patches is <e>highly</e> discouraged. -</p> -</body> - -<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_unpack() { - unpack ${A} - cd "${S}" - epatch "${FILESDIR}/${P}-destdir.patch" - epatch "${FILESDIR}/${P}-parallel_build.patch" -} -</codesample> - -<p> -For larger patches, using <uri link="::general-concepts/mirrors/#suitable-download-hosts">your devspace</uri> rather -than <c>files/</c> is more appropriate. In these situations, it is -usually best to <c>bzip2</c> the patch in question (as opposed to -<c>files/</c> patches, which must not be compressed). For example, -from <c>app-admin/showconsole</c>: -</p> - -<codesample lang="ebuild"> -src_unpack() { - unpack ${A} - cd "${S}" - epatch "${WORKDIR}/${P}-suse-update.patch.bz2" - epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch" -} -</codesample> -<p>As stated before, if you are using EAPI >=2, you should apply the patches in the <uri link="::ebuild-writing/functions/src_prepare">src_prepare</uri> function</p> -<codesample lang="ebuild"> -src_prepare() { - epatch "${WORKDIR}/${P}-suse-update.patch.bz2" - epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch" -} -</codesample> - -<p> -Remember to add the patch to <c>SRC_URI</c>. -</p> -</body> - -<subsection> -<title>CVS Keyword Lines and Patches</title> -<body> -<p> -If your patch includes any changes to CVS <c>$Id: $</c> -(or <c>$Header: $</c>, or <c>$Date: $</c>) lines, it cannot be -distributed under <c>files/</c>, since CVS will clobber the patch when -you commit. In these situations, either remove this hunk of the patch -manually, or mirror the file. -</p> -</body> -</subsection> - -</section> - -<section> -<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_unpack() { - unpack ${A} - cd "${S}" - 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 29b1588..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> @@ -31,15 +31,38 @@ <section> <title>Default <c>src_prepare</c></title> <body> + <p> -Starting from EAPI="2", the src_prepare function is the appropriate area to perform -any kind of patching and source code manipulation, instead of src_unpack. +Before EAPI 6, the default implementation did nothing: </p> + <codesample lang="ebuild"> src_prepare() { - true; + true } </codesample> + +<p> +Beginning with EAPI 6, the src_prepare function gained a new default +implementation: +</p> + +<codesample lang="ebuild"> +src_prepare() { + if [[ $(declare -p PATCHES 2>/dev/null) == "declare -a"* ]]; then + [[ -n ${PATCHES[@]} ]] && eapply "${PATCHES[@]}" + else + [[ -n ${PATCHES} ]] && eapply ${PATCHES} + fi + eapply_user +} +</codesample> + +<note> +With EAPI 6, you must call <c>eapply_user</c> or <c>default</c> if you define +<c>src_prepare</c>! +</note> + </body> </section> @@ -48,16 +71,30 @@ src_prepare() { <body> <codesample lang="ebuild"> src_prepare() { - epatch "${FILESDIR}/${PV}/${P}-fix-bogosity.patch" - use pam && epatch "${FILESDIR}/${PV}/${P}-pam.patch" + eapply "${FILESDIR}/${PV}/${P}-fix-bogosity.patch" + eapply "${FILESDIR}/${PV}/${P}-pam.patch" + + eapply_user - sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!" + sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!" } </codesample> </body> </section> +<section> +<title><c>src_prepare</c> processes</title> +<body> +<p> +The following subsections cover different topics which often occur +when writing <c>src_prepare</c> functions. +</p> + +<contentsTree/> +</body> +</section> + </chapter> -<include href="epatch/"/> +<include href="eapply/"/> <include href="autopackage/"/> </guide> diff --git a/ebuild-writing/functions/src_test/text.xml b/ebuild-writing/functions/src_test/text.xml index dd02d4b..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> @@ -31,23 +31,13 @@ <section> <title>Default <c>src_test</c></title> <body> -<p> From sys-apps/portage-2.1.2.9 </p> +<p>The default test phase in EAPI 6 is equivalent to the following:</p> <codesample lang="ebuild"> src_test() { - if emake -j1 check -n &> /dev/null; then - vecho ">>> Test phase [check]: ${CATEGORY}/${PF}" - if ! emake -j1 check; then - hasq test $FEATURES && die "Make check failed. See above for details." - hasq test $FEATURES || eerror "Make check failed. See above for details." - fi - elif emake -j1 test -n &> /dev/null; then - vecho ">>> Test phase [test]: ${CATEGORY}/${PF}" - if ! emake -j1 test; then - hasq test $FEATURES && die "Make test failed. See above for details." - hasq test $FEATURES || eerror "Make test failed. See above for details." - fi - else - vecho ">>> Test phase [none]: ${CATEGORY}/${PF}" + if nonfatal emake check -n &> /dev/null; then + emake check + elif nonfatal emake test -n &> /dev/null; then + emake test fi } </codesample> @@ -59,34 +49,52 @@ src_test() { <body> <codesample lang="ebuild"> src_test() { - cd "${S}"/src/testdir + cd "${S}"/src/testdir || die - # Test 49 won't work inside a portage environment - sed -i -e 's~test49.out~~g' Makefile + # Test 49 won't work inside a Portage environment + sed -i -e 's~test49.out~~g' Makefile || die - # Try to run the non-gui tests only - make test-nongui \ - || die "At least one test failed" + # Try to run the non-gui tests only + # pass -j1 if tests do not support being run in parallel + emake -j1 test-nongui } </codesample> </body> </section> <section> -<title>Common <c>src_test</c> Tasks</title> +<title>Supporting test suites in packages</title> <body> + +<p> +If the packaged software is equipped with a test suite, it is sensible +to run it. Sometimes the package will need additional dependencies for this, +i.e., dependencies that are only required to run the test suite. Such test-only +dependencies should be specified in DEPEND or BDEPEND behind a USE flag; +often, the <c>test</c> USE flag will be used for this. Please refer to the +section on <uri link="::general-concepts/dependencies/#Test dependencies"/> +for more information. +</p> + +<p> +Note that the <c>test</c> USE flag is only necessary if there are +test dependencies, tests are being built conditionally, or it is desirable +to vary behaviour based on whether tests will be run (e.g. downloading large +files in SRC_URI). It is not appropriate to use the flag to simply indicate that +tests exist and are expected to pass. +</p> + <p> Often the default <c>src_test</c> is fine. Sometimes it is necessary to remove certain tests from the list if they cannot be used with a -portage environment. Reasons for such a failure could include: +Portage environment. Reasons for such a failure could include: </p> <ul> - <li>Needing to use X.</li> <li> Needing to work with files which are disallowed by the sandbox. </li> - <li>Requiring user input (src_test must not be interactive).</li> + <li>Requiring user input (<c>src_test</c> must not be interactive).</li> <li>Requiring root privileges.</li> </ul> @@ -96,45 +104,172 @@ using <c>sed</c> or skipping a particular <c>make</c> target is sufficient. </p> +<p> +Try to ensure that tests work properly for your ebuild. A good test +suite is extremely helpful for arch maintainers. +Sometimes it is necessary to skip tests entirely. This can be done by +setting <c>RESTRICT="test"</c> in the ebuild. +</p> + <note> -<c>emake</c> should not be used for <c>src_test</c> <d/> trying to -parallelise tests unless the <c>Makefile</c> was specifically designed -for this can cause all sorts of strange problems. +If upstream provides a test suite that doesn't work, consider talking +to them about getting it fixed. A broken test suite requires developers +to investigate each test failure in order to determine whether it is +genuine or indicates a broken test. </note> +</body> +</section> +<section> +<title>Tests that require network or service access</title> +<body> <p> -Try to ensure that tests work properly for your ebuild. A good test -suite is extremely helpful for arch maintainers. +Sometimes test suites (and other build-time programs) attempt to use +remote or local network, or production servers running on the host. All +of these are strictly forbidden. Developers should either fix such tests +to work in an isolated environment, or disable them completely unless +explicitly allowed by the user. At the bare minimum, the tests must +not fail with <c>FEATURES=network-sandbox</c> being enabled. +</p> + +<p> +Internet access within the build procedure is forbidden for +the following reasons: +</p> +<ul> + <li> + the build may be running in an environment with no or restricted + Internet access, and this must not cause the tests (build) to fail; + </li> + + <li> + the Internet connection may be unstable (e.g. poor reception) + in which case an interrupted connection or packet loss must not + cause the tests to fail or hang, and it should not cause unnecessary + delays; + </li> + + <li> + the Internet connection may be running on a limited data plan + in which case the additional network use may cause additional + charges or other inconveniences to the user; + </li> + + <li> + the remote network services used by the tests may become unavailable + temporarily or permanently, causing unexpected test failures; + </li> + + <li> + accessing remote sites always poses a privacy issue, and possibly + a threat to security (e.g. through inadvertently exposing + information about the system). + </li> +</ul> + +<p> +Fixing tests that require Internet access usually requires cooperation +with upstream, and porting the tests to use test techniques such as +mocking or using replay data. For this reason, developers report +the issue upstream and skip tests that require network access. +It is recommended to explicitly leave a note as to why the tests are +skipped, so that other developers can re-enable them locally to run +a more complete test suite. +</p> + +<p> +It is generally considered acceptable to rely on IPv4 <c>localhost</c> being +resolvable and available for binding. Tests should only connect to services +that are started as part of the testsuite. It is not acceptable to connect +to daemons run outside the test environment. +</p> + +<p> +Local server access within the build procedure is forbidden for the following +reasons: +</p> + +<ul> + <li> + tests must run reliably independently of whether a particular + server is running throughout the build process or not, + </li> + + <li> + using production services for running tests is extremely + <b>dangerous</b> as it may inadvertently expose bugs in those + services, causing instability, data loss or even exposing security + vulnerabilities. + </li> +</ul> + +<p> +Fixing tests that require access to local services is usually done +via starting additional isolated instances of those services during +the test phase. Those services must either be running on a UNIX +socket or on the loopback interface, to reliably prevent remote access. +</p> + +<p> +For all networked services exposed during the test phase (either by +the ebuild or the tests themselves), UNIX sockets are strongly preferred +over IP sockets as they provide better means for unique naming +and access control mechanisms. IP sockets can be subject to port +collisions with other local services and they can be accessed by local +system users who may exploit a vulnerability through the tests. +</p> + +<p> +Additional protection against those issues is provided through +<c>FEATURES=network-sandbox</c>. However, this is only an optional +Portage feature relying on specific Linux kernel namespace mechanisms +and developers should not rely on it being enabled. </p> </body> </section> <section> -<title>Skipping Tests</title> +<title>Tests that require X11</title> <body> <p> -Sometimes it is necessary to skip tests entirely. This can be done -using a dummy <c>src_test</c> function: +Some packages include tests (or other build-time applications) that +attempt to use the user's X11 session and fail being unable to connect +to it. Those tests need to be fixed to work independently of the X11 +server that might or might not be running when packages are being built. +</p> + +<p> +If the program in question does not strictly need X11 but merely +attempts to take opportunity of the <c>DISPLAY</c> variable being set, +the best solution is to simply unset this variable in the ebuild. </p> <codesample lang="ebuild"> src_test() { - # Tests don't even remotely work inside portage - true + # tests attempt to connect to X11 and fail when it is set + # however, they work just fine without X11 + unset DISPLAY + + default } </codesample> <p> -Another option would be to set <c>RESTRICT="test"</c> in the ebuild. +If the package actually requires a running X11 server to run +the complete test suite, you can use the <c>virtualx</c> eclass to +provide an isolated Xvfb environment for the tests to use. It provides +a virtual X11 display that is not connected to any physical device +and that programs can use reliably. </p> -<note> -If upstream provide a test suite which doesn't work, consider talking -to them about getting it fixed. A broken test suite is worse than no -test suite at all, since we are unable to tell whether a test failure -indicates a genuine fault. -</note> +<codesample lang="ebuild"> +inherit virtualx + +src_test() { + virtx default +} +</codesample> </body> </section> diff --git a/ebuild-writing/functions/src_unpack/cvs-sources/text.xml b/ebuild-writing/functions/src_unpack/cvs-sources/text.xml deleted file mode 100644 index 2f24cc7..0000000 --- a/ebuild-writing/functions/src_unpack/cvs-sources/text.xml +++ /dev/null @@ -1,190 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/cvs-sources/"> -<chapter> -<title>CVS Sources</title> - -<body> -<p> -Rather than working with a source tarball, it is possible to use -upstream's CVS server directly. This can be useful when there is a -need to test unreleased snapshots on a regular basis. -</p> -</body> - -<section> -<title>Disadvantages of CVS Sources</title> -<body> - -<p> -Note that CVS ebuilds should <b>not</b> generally be added to the tree -for the following reasons: -</p> - -<ul> - <li> - Upstream CVS servers tend to be far less reliable than our mirroring - system. - </li> - <li> - CVS ebuilds create a very heavy server load <d/> not only is CVS not - mirrored, but allowing a CVS checkout is considerably more work for - a server than simply serving up a file via HTTP or FTP. - </li> - <li> - Many users who are behind strict firewalls cannot use CVS. - </li> -</ul> - -<p> -It is safer to make a snapshot instead. For example, vim snapshots are made using: -</p> - -<pre> -$ cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vim export -r HEAD vim -</pre> -</body> -</section> - -<section> -<title>Disadvantages of CVS Live Sources</title> -<body> - -<p> -CVS ebuilds which work against CVS <c>HEAD</c> rather than a specific -date or revision are even worse candidates for tree inclusion: -</p> - -<ul> - <li> - You can never be sure whether upstream's CVS will actually - build at any given point; which will most likely cause QA issues. - </li> - <li> - It is extremely difficult to track down bugs when you cannot install - the same version of a package as the reporter. - </li> - <li> - Many upstream package maintainers tend to get upset if people aren't - using a specific released version. - </li> -</ul> - -</body> -</section> - -<section> -<title>Using CVS Sources</title> -<body> - -<note> -CVS ebuilds must be either with empty <c>KEYWORDS</c> or -package.masked (but <e>not</e> both). Empty <c>KEYWORDS</c> are -strongly preferred. This applies to "live" ebuilds (<c>-9999</c>) and -to ebuilds that extract a static revision but still use CVS for -fetching. -</note> - -<p> -To use a CVS source, <c>cvs.eclass</c> must be inherited, and then a -number of variables must be set. The following variables are often -useful: -</p> - -<table> - <tr> - <th>Variable</th> - <th>Purpose</th> - <th>Example</th> - </tr> - <tr> - <ti><c>ECVS_SERVER</c></ti> - <ti>Server and path</ti> - <ti><c>"cvs.sourceforge.net:/cvsroot/vim"</c></ti> - </tr> - <tr> - <ti><c>ECVS_MODULE</c></ti> - <ti>Module</ti> - <ti><c>"vim"</c></ti> - </tr> - <tr> - <ti><c>ECVS_BRANCH</c></ti> - <ti>Branch</ti> - <ti><c>"HEAD"</c></ti> - </tr> - <tr> - <ti><c>ECVS_AUTH</c></ti> - <ti>Auth method</ti> - <ti><c>"ext"</c></ti> - </tr> - <tr> - <ti><c>ECVS_USER</c></ti> - <ti>Username</ti> - <ti><c>"anoncvs"</c></ti> - </tr> - <tr> - <ti><c>ECVS_PASS</c></ti> - <ti>Password</ti> - <ti><c>""</c></ti> - </tr> - <tr> - <ti><c>ECVS_TOPDIR</c></ti> - <ti>Unpack location</ti> - <ti><c>"${DISTDIR}/cvs-src/${ECVS_MODULE}"</c></ti> - </tr> -</table> - -<p> -See the eclass itself for the full range of options. To perform the -actual checkout, use the <c>cvs_src_unpack</c> function. -</p> - -<p> -Here's a simple example, based upon the CVS options in vim.eclass: -</p> - -<codesample lang="ebuild"> -inherit cvs - -SRC_URI="" - -src_unpack() { - ECVS_SERVER="cvs.sourceforge.net:/cvsroot/vim" - ECVS_USER="anonymous" - ECVS_PASS="" - ECVS_AUTH="pserver" - if [[ $(get_major_version ) -ge 7 ]] ; then - ECVS_MODULE="vim7" - else - ECVS_MODULE="vim" - fi - ECVS_TOP_DIR="${DISTDIR}/cvs-src/${ECVS_MODULE}" - cvs_src_unpack -} -</codesample> - -<p> -Here's another approach, based upon the <c>emacs-cvs</c> ebuild, which -relies upon the default <c>src_unpack</c> provided in the eclass; this -approach is simpler but less flexible: -</p> - -<codesample lang="ebuild"> -inherit cvs - -ECVS_AUTH="ext" -CVS_RSH="ssh" -ECVS_SERVER="savannah.gnu.org:/cvsroot/emacs" -ECVS_MODULE="emacs" -ECVS_BRANCH="emacs-unicode-2" -ECVS_USER="anoncvs" -ECVS_PASS="" -ECVS_CVS_OPTIONS="-dP" - -# ...and so on. No src_unpack() is specified. -</codesample> - -</body> -</section> - -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/deb-sources/text.xml b/ebuild-writing/functions/src_unpack/deb-sources/text.xml deleted file mode 100644 index bdbadb4..0000000 --- a/ebuild-writing/functions/src_unpack/deb-sources/text.xml +++ /dev/null @@ -1,12 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/deb-sources/"> -<chapter> -<title>Debian Sources</title> - -<body> -<todo> -from vapier: we dont have to 'handle' these because all debian packages have a source tarball ... the .deb format is pretty simple though, it's managed by the 'ar' utility from binutils. you can unpack a .deb by simply doing ar x blah.deb ... this will give you three files: debian-binary: plain text file which just contains version number of the .deb format control.tar.gz: a few files which control installing/verifying of package data.tar.gz: all the compiled files ... you could just extract it to / -</todo> -</body> -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/other-formats/text.xml b/ebuild-writing/functions/src_unpack/other-formats/text.xml index 3647c80..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 dcf9113..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> @@ -19,16 +19,16 @@ that will unpack the RPM files. </p> <p> -If you do need to apply patches then override <c>src_unpack</c> in a +If you do need to call additional unpack functions then override <c>src_unpack</c> in a manner such as: </p> <codesample lang="ebuild"> -src_unpack () { - rpm_src_unpack ${A} - cd "${S}" +src_unpack() { + rpm_src_unpack ${A} + cd "${S}" - use ssl && epatch "${FILESDIR}/${PV}/${P}-ssl.patch" + use ssl && eapply "${FILESDIR}/${PV}/${P}-ssl.patch" } </codesample> @@ -40,7 +40,7 @@ format. </body> <section> -<title>Example RPM Handling</title> +<title>Example RPM handling</title> <body> <p> @@ -52,18 +52,20 @@ patches. The filename should be <c>suse-fetchmail-6.2.5.54.1.ebuild</c>. </p> <codesample lang="ebuild"> -# Copyright 1999-2005 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -inherit eutils versionator rpm +EAPI=7 + +inherit rpm -MY_PV=$(replace_version_separator 3 '-') +MY_PV=$(ver_rs 3 '-') MY_P=fetchmail-${MY_PV} -SRC_URI="http://suse.osuosl.org/suse/i386/9.2/suse/src/${MY_P}.src.rpm" DESCRIPTION="SuSE 9.2 Fetchmail Source Package" -HOMEPAGE="http://www.suse.com" +HOMEPAGE="https://www.suse.com" +SRC_URI="https://suse.osuosl.org/suse/i386/9.2/suse/src/${MY_P}.src.rpm" +S=${WORKDIR}/fetchmail-$(ver_cut 1-3) LICENSE="GPL-2 public-domain" SLOT="0" @@ -74,20 +76,22 @@ RESTRICT="mirror" # Need to test if the file can be unpacked with rpmoffset and cpio # If it can't then set: -#DEPEND="app-arch/rpm" +#BDEPEND="app-arch/rpm" # To force the use of rpmoffset and cpio instead of rpm2cpio from # app-arch/rpm, then set the following: #USE_RPMOFFSET_ONLY=1 -S=${WORKDIR}/fetchmail-$(get_version_component_range 1-3) - -src_unpack () { +src_unpack() { rpm_src_unpack ${A} - cd "${S}" - EPATCH_SOURCE="${WORKDIR}" EPATCH_SUFFIX="patch" \ - EPATCH_FORCE="yes" epatch +} + +src_prepare() { + for i in "${WORKDIR}"/*.patch ; do + eapply "${i}" + done + eapply_user } </codesample> diff --git a/ebuild-writing/functions/src_unpack/svn-sources/text.xml b/ebuild-writing/functions/src_unpack/svn-sources/text.xml deleted file mode 100644 index e436c97..0000000 --- a/ebuild-writing/functions/src_unpack/svn-sources/text.xml +++ /dev/null @@ -1,116 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/svn-sources/"> -<chapter> -<title>Subversion Sources</title> - -<body> -<p> -As with CVS, an eclass exists for working directly with upstream -Subversion repositories. See <uri link="::eclass-reference/subversion.eclass/">subversion.eclass</uri> -for a full list of functions and variables. Also see -the <uri link="::ebuild-writing/functions/src_unpack/cvs-sources"/> -ection. -</p> -</body> - -<section> -<title>Disadvantages of Subversion Sources</title> -<body> - -<p> -Note that Subversion ebuilds should <b>not</b> generally be added to -the tree for much the same reasons that live CVS ebuilds should not (see -<uri link="::ebuild-writing/functions/src_unpack/cvs-sources#Disadvantages of CVS Sources"/>). -Indeed, there should be even less impetus to add a live Subversion ebuild than a live CVS ebuild, as -Subversion checkouts are roughly a factor of five larger than an -equivalent CVS checkout. -</p> - -<p> -It is safer (and better for the user) to make a snapshot instead. For -example, <c>gentoo-syntax</c> snapshots could be made using: -</p> - -<pre> -$ svn export svn://svn.berlios.de/svnroot/repos/gentoo-syntax -r HEAD gentoo-syntax -</pre> -</body> -</section> - -<section> -<title>Using Subversion Sources</title> -<body> - -<note> -Subversion ebuilds must be either with empty <c>KEYWORDS</c> or -package.masked (but <e>not</e> both). Empty <c>KEYWORDS</c> are -strongly preferred. This applies to "live" ebuilds (<c>-9999</c>) and -to ebuilds that extract a static revision but still use Subversion for -fetching. -</note> - -<p> -To use a Subversion source, <c>subversion.eclass</c> must be -inherited, and then at least <c>ESVN_REPO_URI</c> must be set. The -following variables are also noteworthy: -</p> - -<table> - <tr> - <th>Variable</th> - <th>Purpose</th> - <th>Example</th> - </tr> - <tr> - <ti><c>ESVN_REPO_URI</c></ti> - <ti>Server and path (http, https, svn)</ti> - <ti><c>"svn://svn.example.com/foobar/trunk"</c></ti> - </tr> - <tr> - <ti><c>ESVN_STORE_DIR</c></ti> - <ti>Unpack location</ti> - <ti><c>ESVN_STORE_DIR="${DISTDIR}/svn-src"</c></ti> - </tr> - <tr> - <ti><c>ESVN_PROJECT</c></ti> - <ti>Project name of ebuild</ti> - <ti><c>ESVN_PROJECT="${PN/-svn}"</c></ti> - </tr> - <tr> - <ti><c>ESVN_BOOTSTRAP</c></ti> - <ti>Bootstrap command or script</ti> - <ti><c>ESVN_BOOTSTRAP="autogen.sh"</c></ti> - </tr> - <tr> - <ti><c>ESVN_PATCHES</c></ti> - <ti>Patches to apply during bootstrap</ti> - <ti><c>ESVN_PATCHES="${FILESDIR}/*.patch"</c></ti> - </tr> -</table> - -<p> -See the eclass itself and <uri link="::eclass-reference/subversion.eclass/">subversion.eclass</uri> -for the full range of options. To perform the actual checkout, use -the <c>subversion_src_unpack</c> function, which calls -both <c>subversion_svn_fetch</c> and <c>subversion_bootstrap</c> -itself. -</p> - -<p> -Here is a simple example, based upon the Subversion options in -<c>litu-svn-20040902.ebuild</c>; this approach is sufficient for most -Subversion ebuilds: -</p> - -<codesample lang="ebuild"> -inherit subversion - -ESVN_REPO_URI="http://tao.uab.es/ion/svn/libtu/trunk" -ESVN_PROJECT="libtu-snapshot" -</codesample> - -</body> -</section> - -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/text.xml b/ebuild-writing/functions/src_unpack/text.xml index 542b3fb..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> @@ -11,7 +11,7 @@ </tr> <tr> <th>Purpose</th> - <ti>Extract source packages and do any necessary patching or fixes.</ti> + <ti>Extract source packages.</ti> </tr> <tr> <th>Sandbox</th> @@ -33,9 +33,9 @@ <body> <codesample lang="ebuild"> src_unpack() { - if [ "${A}" != "" ]; then - unpack ${A} - fi + if [[ -n ${A} ]]; then + unpack ${A} + fi } </codesample> </body> @@ -44,26 +44,19 @@ src_unpack() { <section> <title>Sample <c>src_unpack</c></title> <body> + <codesample lang="ebuild"> src_unpack() { - unpack ${A} - cd "${S}" - - epatch "${FILESDIR}/${PV}/${P}-fix-bogosity.patch" - use pam && epatch "${FILESDIR}/${PV}/${P}-pam.patch" - - sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!" + unpack ${P}.tar.xz + use foo && unpack ${P}-foo-extension.tar.xz } </codesample> -<note> -When using EAPI >=2, you should use the <uri link="::ebuild-writing/functions/src_prepare">src_prepare</uri> function to apply patches or alter any of the source files, instead of the src_unpack. -</note> </body> </section> <section> -<title>Unpacking Tarballs</title> +<title>Unpacking tarballs</title> <body> <p> The <c>unpack</c> function should be used to unpack tarballs, compressed @@ -80,7 +73,43 @@ usually simpler to avoid working with <c>${A}</c>. </section> <section> -<title><c>src_unpack</c> Actions</title> +<title>Known file formats</title> +<body> + +<p> +The <c>unpack</c> function recognizes the following file formats: +</p> + +<ul> + <li><c>*.tar</c></li> + <li> + <c>*.gz</c>, <c>*.Z</c>, + <c>*.tar.gz</c>, <c>*.tgz</c>, <c>*.tar.Z</c> + </li> + <li> + <c>*.bz2</c>, <c>*.bz</c>, + <c>*.tar.bz2</c>, <c>*.tbz2</c>, <c>*.tar.bz</c>, <c>*.tbz</c> + </li> + <li><c>*.lzma</c>, <c>*.tar.lzma</c></li> + <li><c>*.xz</c>, <c>*.tar.xz</c>, <c>*.txz</c></li> + <li><c>*.zip</c>, <c>*.ZIP</c>, <c>*.jar</c></li> + <li><c>*.a</c>, <c>*.deb</c></li> +</ul> + +<p> +In EAPI 6 and later, filename extensions are matched case-insensitively. +</p> + +<important> +Unless the utility needed for unpacking is in the system set, the ebuild must +specify the necessary build time dependency (<c>BDEPEND</c>) for it. +</important> + +</body> +</section> + +<section> +<title><c>src_unpack</c> actions</title> <body> <p> The following subsections cover different topics which often occur when writing @@ -93,10 +122,7 @@ The following subsections cover different topics which often occur when writing </chapter> -<include href="cvs-sources/"/> -<include href="svn-sources/"/> -<include href="tla-sources/"/> +<include href="vcs-sources/"/> <include href="rpm-sources/"/> -<include href="deb-sources/"/> <include href="other-formats/"/> </guide> diff --git a/ebuild-writing/functions/src_unpack/tla-sources/text.xml b/ebuild-writing/functions/src_unpack/tla-sources/text.xml deleted file mode 100644 index 97a8b40..0000000 --- a/ebuild-writing/functions/src_unpack/tla-sources/text.xml +++ /dev/null @@ -1,12 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/tla-sources/"> -<chapter> -<title>Arch Sources</title> - -<body> -<todo> -Anyone want to write this? You can probably mostly copy the CVS Sources and Subversion Sources chapters. -</todo> -</body> -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/vcs-sources/text.xml b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml new file mode 100644 index 0000000..68fbe91 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml @@ -0,0 +1,100 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-writing/functions/src_unpack/vcs-sources/"> +<chapter> +<title>Version Control System (VCS) sources</title> +<body> + +<p> +Rather than working with a source tarball, it is possible to use upstream +source code repositories directly. This can be useful when there is a need to +test unreleased snapshots on a regular basis. A number of eclasses exists for +this purpose; see their documentation for a list of available functions and +variables. +</p> + +<ul> + <li><uri link="::eclass-reference/cvs.eclass/"/></li> + <li><uri link="::eclass-reference/darcs.eclass/"/></li> + <li><uri link="::eclass-reference/git-r3.eclass/"/></li> + <li><uri link="::eclass-reference/mercurial.eclass/"/></li> + <li><uri link="::eclass-reference/subversion.eclass/"/></li> +</ul> + +<note> +VCS ebuilds must be with empty <c>KEYWORDS</c> but <e>not</e> package.masked +(except if the mask is for an independent reason). Usually the <c>KEYWORDS</c> +line should be omitted altogether. This applies to "live" ebuilds (<c>-9999</c>) +and to ebuilds that extract a static revision but still use a version control +system for fetching. +</note> + +</body> + +<section> +<title>Disadvantages of VCS sources</title> +<body> + +<p> +Note that VCS ebuilds should <b>not</b> generally be added to the tree for the +following reasons: +</p> + +<ul> + <li> + Upstream VCS servers tend to be far less reliable than our mirroring + system. + </li> + <li> + VCS ebuilds create a very heavy server load <d/> not only are repositories + not mirrored, but fetching sources from them is considerably more work for + a server than simply serving up a file via HTTP or FTP. + </li> + <li> + Local copies of a repository are several times larger than a tarball of the + same sources, and tend to grow over time because they include the history. + </li> + <li> + Many users who are behind strict firewalls cannot use protocols like CVS. + </li> +</ul> + +<p> +It is safer (and better for the user) to make a snapshot instead. For example, +<c>app-editors/emacs</c> snapshots are made using: +</p> + +<pre> +$ git archive --prefix=emacs/ HEAD | xz > emacs-${PV}.tar.xz +</pre> + +</body> +</section> + +<section> +<title>Disadvantages of VCS live sources</title> +<body> + +<p> +VCS ebuilds that work against the latest head (or tip) rather than a specific +date or revision are even worse candidates for tree inclusion: +</p> + +<ul> + <li> + You can never be sure whether upstream's source will actually build at any + given point; which will most likely cause QA issues. + </li> + <li> + It is extremely difficult to track down bugs when you cannot install the + same version of a package as the reporter. + </li> + <li> + Many upstream package maintainers tend to get upset if people aren't using + a specific released version. + </li> +</ul> + +</body> +</section> +</chapter> +</guide> diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml index d10a51f..c5a6cbc 100644 --- a/ebuild-writing/functions/text.xml +++ b/ebuild-writing/functions/text.xml @@ -1,20 +1,38 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/"> <chapter> -<title>Ebuild Functions</title> +<title>Ebuild phase functions</title> <body> <p> -When installing packages from source, the function call order is <c>pkg_setup</c>, -<c>src_unpack</c>, <c>src_prepare</c>, <c>src_compile</c>, <c>src_test</c> (optional, <c>FEATURES="test"</c>), -<c>src_install</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. When installing packages -from a binary, the function call order is <c>pkg_setup</c>, <c>pkg_preinst</c>, -<c>pkg_postinst</c>. -As some phases haven't been introduced from the beginning, you can have a look at -<uri link="::ebuild-writing/eapi"/> for an overview, what have been introduced in which EAPI. +When installing packages from source, the phase function call order is +<c>pkg_pretend</c>, <c>pkg_setup</c>, +<c>src_unpack</c>, <c>src_prepare</c>, <c>src_configure</c>, <c>src_compile</c>, +<c>src_test</c> (optional, <c>FEATURES="test"</c>), +<c>src_install</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. When installing +packages from a binary, the phase function call order is <c>pkg_pretend</c>, +<c>pkg_setup</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. +As some phases haven't been introduced from the beginning, you can have a look +at <uri link="::ebuild-writing/eapi/"/> for an overview, what have been +introduced in which EAPI. </p> -<figure short="How the ebuild functions are processed" link="diagram.png"/> +<p> +Ebuilds should usually define phases in the order they are called, +as set out above, for readability. +</p> + +<figure short="How the ebuild phase functions are processed" link="diagram.png"/> + +<p> +The <c>pkg_pretend</c> function is to be used for performing various +early sanity checks, such as ensuring that certain kernel options are +enabled. It is important to keep in mind that <c>pkg_pretend</c> runs +separately from the rest of the phase function sequence. Consequently, +there is no environment saving or propagation to the next +phase. Moreover, ebuild dependencies are not guaranteed to be +satisfied at this phase. +</p> <p> The <c>pkg_prerm</c> and <c>pkg_postrm</c> functions are called when uninstalling a @@ -31,8 +49,9 @@ location, and Portage records digests of the files installed. </p> <p> -When testing or debugging, you can instruct Portage to execute a specific function -from an ebuild by using the <c>ebuild</c> command, see the <c>ebuild(1)</c> manual +When testing or debugging, you can instruct Portage to execute a +specific phase function of an ebuild by using the <c>ebuild</c> +command, see the <c>ebuild(1)</c> manual page for further information. </p> @@ -41,14 +60,51 @@ Downloading a package's source happens before any of these phases, so <c>emerge --fetchonly</c> should perform all the network access you need (unless you're using live ebuilds). Network access outside of this would not be cached locally (e.g. in <c>${DISTDIR}</c>, see -<uri link="::ebuild-writing/variables#Predefined Read-Only Variables."/>), +<uri link="::ebuild-writing/variables/#Predefined read-only variables"/>), which makes it hard to have reproducible builds (see -<uri link="::ebuild-writing/functions/src_unpack/cvs-sources#Disadvantages of CVS Sources"/>). +<uri link="::ebuild-writing/functions/src_unpack/vcs-sources/#Disadvantages of vcs sources"/>). Avoid network access in any phase by using local files, extending <c>SRC_URI</c> (see -<uri link="::ebuild-writing/variables#Ebuild-defined Variables"/>), etc. +<uri link="::ebuild-writing/variables/#Ebuild-defined variables"/>), etc. +</p> +</body> + +<section> +<title>Default phase functions</title> +<body> + +<p> +The default <c>pkg_nofetch</c> and <c>src_*</c> phase functions are accessible +via a function having a name that begins with <c>default_</c> and ends with the +respective phase function name. For example, a call to a function with the name +<c>default_src_compile</c> is equivalent to a call to the default +<c>src_compile</c> implementation. +</p> + +<p> +The default phase functions are: </p> + +<ul> + <li><c>default_pkg_nofetch</c></li> + <li><c>default_src_unpack</c></li> + <li><c>default_src_prepare</c></li> + <li><c>default_src_configure</c></li> + <li><c>default_src_compile</c></li> + <li><c>default_src_test</c></li> + <li><c>default_src_install</c></li> +</ul> + +<p> +A function named <c>default</c> is redefined for each of the above phases, +so that it will call the <c>default_*</c> function corresponding to +the current phase. For example, a call to the <c>default</c> function +during the <c>src_compile</c> phase is equivalent to a call to the +<c>default_src_compile</c> function. +</p> + </body> +</section> <section> <title>Contents</title> |
