commit: cb01d9ebc777517fce784dde4f8cdbf78d91b5bf Author: Ulrich Müller <ulm <AT> gentoo <DOT> org> AuthorDate: Tue Jan 21 10:34:07 2020 +0000 Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org> CommitDate: Thu Jan 23 07:48:05 2020 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=cb01d9eb
ebuild-maintenance/new-ebuild: New chapter. Split off from ebuild-maintenance/maintenance-tasks. Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org> ebuild-maintenance/maintenance-tasks/text.xml | 123 ------------------------- ebuild-maintenance/new-ebuild/text.xml | 126 ++++++++++++++++++++++++++ ebuild-maintenance/text.xml | 1 + ebuild-writing/common-mistakes/text.xml | 3 +- 4 files changed, 128 insertions(+), 125 deletions(-) diff --git a/ebuild-maintenance/maintenance-tasks/text.xml b/ebuild-maintenance/maintenance-tasks/text.xml index b5b7359..972b7b3 100644 --- a/ebuild-maintenance/maintenance-tasks/text.xml +++ b/ebuild-maintenance/maintenance-tasks/text.xml @@ -11,129 +11,6 @@ developers may not be familiar with. </p> </body> -<section> -<title>Adding a new ebuild</title> - -<subsection> -<title>What (not) to put in the Gentoo repository</title> -<body> - -<p> -Before writing a new ebuild, check -<uri link="https://bugs.gentoo.org/";>bugs.gentoo.org</uri> -to see if an ebuild has already been written for the package, but has not yet -been added to the Gentoo repository. Go to <uri -link="https://bugs.gentoo.org/";>bugs.gentoo.org</uri>, choose query and select -Advanced Search; as product select <e>Gentoo Linux</e>, as component select -<e>ebuilds</e>. In the search field put the name of the ebuild and as status -select all possible fields, then submit the query. For you lazy people, click -<uri link="https://bugs.gentoo.org/query.cgi?format=advanced&product=Gentoo%20Linux&component=New%20Ebuilds&bug_Status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=IN_PROGRESS&bug_status=RESOLVED&bug_status=VERIFIED";>here</uri>. -</p> - -<p> -In general, the Gentoo repository should only be used for storing -<c>.ebuild</c> files, as well as any relatively small companion -files, such as patches or sample configuration files. These types of -files should be placed in the <c>mycat/mypkg/files</c> directory -to keep the main <c>mycat/mypkg</c> directory uncluttered. -Exceptions to this rule are for larger patch files (we recommend this -for patches above 20KB) which should be distributed as tarballs via the -<uri link="::general-concepts/mirrors/#Suitable Download Hosts">Gentoo -mirror system</uri> so that people do not waste excessive amounts of -bandwidth and hard drive space. Also, you should not add binary -(non-ASCII) files to the git tree. Also, speaking of merging changes, -any patches you add to Portage should generally <e>not</e> be -compressed. This will allow git to merge changes and correctly inform -developers of conflicts. -</p> - -<p> -Remember, the packages that you commit must be <e>ready</e> <e>out of the -box</e> for end users when committed as stable. Make sure that you have a good -set of default settings that will satisfy the majority of systems and -users that will use your package. If your package is broken, and you are -not sure how to get it to work, check some other distributions that have -done their own versions of the package. You can check -<uri link="https://www.debian.org/distrib/packages";>Debian</uri> or -<uri link="https://src.fedoraproject.org/projects/rpms/*";>Fedora</uri> for some -examples. -</p> - -<p> -When committing to git, all developers should use <c>repoman commit</c> -instead of <c>git commit</c> to submit their ebuilds. Before committing, -please run <c>repoman full</c> to make sure you didn't forget something. -</p> - -</body> -</subsection> - -<subsection> -<title>Initial Architecture Keywords</title> -<body> -<p> -When adding a new ebuild, you should only include <c>KEYWORDS</c> for -architectures on which you have actually tested the ebuild, confirming -that it works as it should and that <c>USE</c> flags are properly -honoured in the resulting package which would be installed. If -possible, you should give the actual library or application thorough -testing as well, since you would be responsible for any breakages for -your architecture(s). Minimal testing such as checking that the -application starts up without any errors should always be performed. -</p> - -<p> -If you are adding a user-submitted ebuild, do not assume that the -submitter has done testing on various architectures: often, <c>KEYWORDS</c> -are cloned across packages or generated from documentation in the -source packages, which does not signify that the package does indeed -work on those architectures. -</p> - -</body> -</subsection> - -<subsection> -<title>The files Directory</title> -<body> - -<p> -As noted earlier, under each package subdirectory is -a <c>files/</c> directory. Any patches, configuration files, or -other ancillary files your package might require should be added to -this directory; any files bigger than 20KB-or-so should go to the -mirrors to lower the amount of (unneeded) files our users have to -download. You may want to consider naming patches you create yourself -just to get your package to build with a version-specific name, such -as <c>mypkg-1.0-gentoo.diff</c>, or more -simply, <c>1.0-gentoo.diff</c>. Also note that the -<c>gentoo</c> extension informs people that this patch was created -by us, the Gentoo Linux developers, rather than having been grabbed from a -mailing list or somewhere else. Again, you should not compress these -patches. -</p> - -<p> -Consider prefixing or suffixing (such as <c>mypkg-1.0</c>) every file -you put into the <c>files/</c> directory, so that the files used for -each individual version on an ebuild are distinguishable from one another, and -so that the changes between different revisions are visible. This is generally -a really good idea :). You may want to use a different suffix if you wish to -convey more meaning with the patch name. -</p> - -<p> -If you have many files that should go into the <c>files/</c> directory, -consider creating subdirectories such as <c>files/1.0/</c> and putting the -relevant files in the appropriate subdirectory. If you use this method, -you do not need to add version information to the names of the files, -which is often more convenient. -</p> - -</body> -</subsection> -</section> - <section> <title>Stabilizing ebuilds</title> <body> diff --git a/ebuild-maintenance/new-ebuild/text.xml b/ebuild-maintenance/new-ebuild/text.xml new file mode 100644 index 0000000..332b527 --- /dev/null +++ b/ebuild-maintenance/new-ebuild/text.xml @@ -0,0 +1,126 @@ +<?xml version="1.0"?> +<guide self="ebuild-maintenance/new-ebuild/"> +<chapter> +<title>Adding a New Ebuild</title> + +<section> +<title>What (not) to put in the Gentoo repository</title> +<body> + +<p> +Before writing a new ebuild, check +<uri link="https://bugs.gentoo.org/";>bugs.gentoo.org</uri> +to see if an ebuild has already been written for the package, but has not yet +been added to the Gentoo repository. Go to <uri +link="https://bugs.gentoo.org/";>bugs.gentoo.org</uri>, choose query and select +Advanced Search; as product select <e>Gentoo Linux</e>, as component select +<e>ebuilds</e>. In the search field put the name of the ebuild and as status +select all possible fields, then submit the query. For you lazy people, click +<uri link="https://bugs.gentoo.org/query.cgi?format=advanced&product=Gentoo%20Linux&component=New%20Ebuilds&bug_Status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=IN_PROGRESS&bug_status=RESOLVED&bug_status=VERIFIED";>here</uri>. +</p> + +<p> +In general, the Gentoo repository should only be used for storing +<c>.ebuild</c> files, as well as any relatively small companion +files, such as patches or sample configuration files. These types of +files should be placed in the <c>mycat/mypkg/files</c> directory +to keep the main <c>mycat/mypkg</c> directory uncluttered. +Exceptions to this rule are for larger patch files (we recommend this +for patches above 20KB) which should be distributed as tarballs via the +<uri link="::general-concepts/mirrors/#Suitable Download Hosts">Gentoo +mirror system</uri> so that people do not waste excessive amounts of +bandwidth and hard drive space. Also, you should not add binary +(non-ASCII) files to the git tree. Also, speaking of merging changes, +any patches you add to Portage should generally <e>not</e> be +compressed. This will allow git to merge changes and correctly inform +developers of conflicts. +</p> + +<p> +Remember, the packages that you commit must be <e>ready</e> <e>out of the +box</e> for end users when committed as stable. Make sure that you have a good +set of default settings that will satisfy the majority of systems and +users that will use your package. If your package is broken, and you are +not sure how to get it to work, check some other distributions that have +done their own versions of the package. You can check +<uri link="https://www.debian.org/distrib/packages";>Debian</uri> or +<uri link="https://src.fedoraproject.org/projects/rpms/*";>Fedora</uri> for some +examples. +</p> + +<p> +When committing to git, all developers should use <c>repoman commit</c> +instead of <c>git commit</c> to submit their ebuilds. Before committing, +please run <c>repoman full</c> to make sure you didn't forget something. +</p> + +</body> +</section> + +<section> +<title>Initial Architecture Keywords</title> +<body> + +<p> +When adding a new ebuild, you should only include <c>KEYWORDS</c> for +architectures on which you have actually tested the ebuild, confirming +that it works as it should and that <c>USE</c> flags are properly +honoured in the resulting package which would be installed. If +possible, you should give the actual library or application thorough +testing as well, since you would be responsible for any breakages for +your architecture(s). Minimal testing such as checking that the +application starts up without any errors should always be performed. +</p> + +<p> +If you are adding a user-submitted ebuild, do not assume that the +submitter has done testing on various architectures: often, <c>KEYWORDS</c> +are cloned across packages or generated from documentation in the +source packages, which does not signify that the package does indeed +work on those architectures. +</p> + +</body> +</section> + +<section> +<title>The files Directory</title> +<body> + +<p> +As noted earlier, under each package subdirectory is +a <c>files/</c> directory. Any patches, configuration files, or +other ancillary files your package might require should be added to +this directory; any files bigger than 20KB-or-so should go to the +mirrors to lower the amount of (unneeded) files our users have to +download. You may want to consider naming patches you create yourself +just to get your package to build with a version-specific name, such +as <c>mypkg-1.0-gentoo.diff</c>, or more +simply, <c>1.0-gentoo.diff</c>. Also note that the +<c>gentoo</c> extension informs people that this patch was created +by us, the Gentoo Linux developers, rather than having been grabbed from a +mailing list or somewhere else. Again, you should not compress these +patches. +</p> + +<p> +Consider prefixing or suffixing (such as <c>mypkg-1.0</c>) every file +you put into the <c>files/</c> directory, so that the files used for +each individual version on an ebuild are distinguishable from one another, and +so that the changes between different revisions are visible. This is generally +a really good idea :). You may want to use a different suffix if you wish to +convey more meaning with the patch name. +</p> + +<p> +If you have many files that should go into the <c>files/</c> directory, +consider creating subdirectories such as <c>files/1.0/</c> and putting the +relevant files in the appropriate subdirectory. If you use this method, +you do not need to add version information to the names of the files, +which is often more convenient. +</p> + +</body> +</section> +</chapter> +</guide> diff --git a/ebuild-maintenance/text.xml b/ebuild-maintenance/text.xml index eabda98..58ac723 100644 --- a/ebuild-maintenance/text.xml +++ b/ebuild-maintenance/text.xml @@ -17,6 +17,7 @@ This section covers various tasks related to working with ebuilds. </section> </chapter> +<include href="new-ebuild/"/> <include href="git/"/> <include href="package-moves/"/> <include href="maintenance-tasks/"/> diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index a133037..2127b3f 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -451,8 +451,7 @@ at least when the ebuild hits the stable branch. <p> Please submit ebuilds properly by following the -<uri link="::ebuild-maintenance/maintenance-tasks#Adding a new ebuild"> -Adding new Ebuild</uri> tutorial. +<uri link="::ebuild-maintenance/new-ebuild/"/> tutorial. </p> </body>
