To consolidate all these into the Ebuild HOWTO I suggest the following moves. include: "Ebuild HOWTO" through to "What (not) to put in the Portage tree" clarification: second paragraph s/, as well as any relatively small companion files, such as patches or sample configuration files/ and companion files less than 20 kilobytes such as patches and sample configuration files/ omit 5th paragraph due to consolidation: Double-check the ebuild and cross it with the Common Gentoo ebuild Mistakes section. include up to: "CVS Commit Policy" last dot point needs modification: s/ revised package.mask, then commit the ebuild, ChangeLog and license/ revised package.mask and license, then commit the ebuild, ChangeLog, patches and metadata.xml(link to http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=4)/ include up to: "The files Directory" modify 1st paragraph: s/or other ancillary files your package/or other ancillary files (less than 20 kilobytes in size) your package/ Include up to "1.b. Ebuild scripts" replace "Naming ebuild files" with "Naming policy" from "Ebuild Policy". IMHO it has got a bit more detail. Please check I'm not missing anything. include up to: "Contents of an ebuild file" replace note with ordinary text (personal opinion - up to you) include "Missing/Invalid/Broken Header" from "Common ebuild Mistakes" relabeled as "Ebuild headers" replace /usr/portage/skel.ebuild with /usr/portage/header.txt in included text. before the "varables section" include "CVS sources policy" from the "Ebuild policy" retitled as "CVS ebuilds" include "varables section" with the following mods: KEYWORDS description: s|amd64, ia64. Obviously|amd64, ia64 (refer to /usr/portage/profiles/arch.list). Obviously| SRC_URI description: make a reference to "Including version numbers in SRC_URI and S" from "Common ebuild Mistakes" and copy this to below the table. HOMEPAGE description append: "Never refer to a varible name in this text, just use the raw URL." below table include: "Including version numbers in SRC_URI and S" from "Common ebuild Mistakes" include up until before: 1.c. File system Locations insert before this heading: "1.b. Specific guidelines" from "Ebuild Policy" replace in the copyright inclusion: s/Gentoo Technologies/Gentoo Foundation only/ (note bug 73263 may alter text of fPIC) include 1.c up until: 1.d. The Portage scripts and utilities - Public scripts add the following to the table before "install": test* Runs the test routine to self test the package src_test include up until: 1.e. Package Dependencies replace all s:virtual/glibc:virtual/libc:g before final note in this section: include contents of "DEPEND has syntactical errors" from "Common ebuild Mistakes" Include final note. include "DEPEND is incomplete" from "Common ebuild Mistakes" renamed as "How to ensure dependancies are complete" include up to heading" 1.f Testing and deploying add subheading "Testing the package" with the following text: Have a think about how you will test this package works. Sometime the package developer has already thought of this and included a make test/check routine that will test the basic functionality of the package. If the have this then running "env FEATURE=maketest ebuild {package} test" will execute it. If it is broken try to fix it so that it works (and submit the patch upstream). If this is not the case consider adding a src_test routine to your ebuild. This is executed before the src_install routine and is very helpful for testing the program works across various architectures. The architecture developers will appreciate you add a routine here so they do not require an indepth knowledge of the package. Please keep in mind the general requirements of an ebuild here. The src_test routine must not be interactive. If the test routine depends on other packages use the "maketest" use flag to sepecify optional compile time (DEPEND) dependancies. Also src_test routines are not recommended for X Window applications as the root user often cannot run them. include 1.d. "QA policy" from "Ebuild policy" append to this section: "User-submitted ebuilds" from "Ebuild Policy" include up until "Useful testing tools" Remove warning about lintool - (its far too old)
Going through your suggestions: * 20Kb is too small for some patches IMO, 35Kb should be acceptable. * Not including the "CVS sources policy" from the "Ebuild policy"; since that is aimed at developers rather than users who wish to understand how to develop an ebuild. * Not adding QA policy, again, that is for developers only and should remain in the policy docs. Rest should be done and in CVS, should reach the web nodes within a few hours. Please confirm your requested changes...
20K is already a huge patch to be sitting in the tree. Nobody said you couldn't have a patch bigger than 20K, it just has to be mirrored.
Created attachment 45313 [details, diff] hb-guide-ebuild.patch 20kbytes came from repoman warning limit that came from -dev discussion http://marc.theaimsgroup.com/?l=gentoo-dev&m=109109470932081&w=2 and bug 57532. Further suggestions: moves from Ebuild policy to howto: 1.b. Specific guidelines, Virtuals, Scope, Additions still required: respect for CFLAGS and CC, CXX (and probably a few others) Patch contents: change date atomic commits of license and ebuild isn't possible as they are in different directories. Commiting license and then ebuild is safe. Added content from Ebuild Policy: DEPEND so that they reflect the same content. As such Varibles section of EBuild policy can be removed (along with naming A few other changes to make better use of XML.
Thankyou Tim for all the other changes.
re: respect for CC, CXX... you should mention to use the $(tc_getCC) $(tc_getCXX) etc functions rather than ${CC} directly...
What is the general guidance on when to use $(tc_getCC) like functions? I've been using them for all ebuilds that don't use a propper autoconf. Is this correct? So its basically to eliminate CC=gcc in make files? Can someone list a small rational for the HOWTO docs?
here's the rational ebuilds should never hardcode CC/CXX/LD/RANLIB/etc... if an ebuild needs to make sure these variables are set, they should use the appropriate $(tc-get) function in terms of making packages which dont utilize configure work nicely, package maintainers should force the appropriate setting instead of letting the Makefile hardcode it and/or make pick the default
Created attachment 47190 [details, diff] additional hb-guide-ebuild.patch for toolchain-func.eclass for consideration.
toolchain-funcs goodness in CVS. Thanks!
