diff options
| author |   Ulrich Müller <ulm@gentoo.org> | 2005-07-12 17:21:19 +0000 |
|---|---|---|
| committer | Ulrich Müller <ulm@gentoo.org> | 2020-01-09 23:50:51 +0100 |
| commit | b5eb706b0d006535cb8e48b7a03177249a630dd0 (patch) | |
| tree | bd1ad55b9d89bbe5b185210eb838759e4aa4923e | |
| download | devmanual-b5eb706b0d006535cb8e48b7a03177249a630dd0.tar.gz devmanual-b5eb706b0d006535cb8e48b7a03177249a630dd0.tar.bz2 devmanual-b5eb706b0d006535cb8e48b7a03177249a630dd0.zip | |
reStructuredText source of the devmanual
Taken from ~sekretarz/public_html/devmanual.tar.bz on dev.gentoo.org
and removed all generated HTML, PNG, and temporary files.
Timestamp of oldest file: 2005-06-04 11:50:45 +0000
Timestamp of newest file: 2005-07-12 17:21:19 +0000
Signed-off-by: Ulrich Müller <ulm@gentoo.org>
297 files changed, 9495 insertions, 0 deletions
diff --git a/appendices/common-problems/text.rst b/appendices/common-problems/text.rst new file mode 100644 index 0000000..0eeabf3 --- /dev/null +++ b/appendices/common-problems/text.rst @@ -0,0 +1,133 @@ +Common Problems +=============== + +This page provides suggestions on how to handle various commonly seen errors +and QA notices. + +Handling QA Notices +------------------- + +The ``ebuild.sh`` part of portage includes a number of checks for common +problems. These can result in a 'QA Notice' message being displayed. You must +not rely upon portage always generating these messages -- they are not a +substitute for proper testing and QA by developers. + +.. Note:: Some eclasses output messages in the same format. These are not + covered here. + +QA Notice -- USE Flag foo not in IUSE +''''''''''''''''''''''''''''''''''''' + +With the exception of 'special' flags (the arch flags and ``USE_EXPAND`` +variables), all ``USE`` flags used by a package must be included in ``IUSE``. +See `IUSE`_ and `USE Flags`_. + +QA Notice -- foo in global scope +'''''''''''''''''''''''''''''''' + +This message occurs when various tools are inappropriately used in global scope. +Remember that no external code should be run globally. Depending upon the tool +in use, there are various alternatives: + +``sed``, ``awk``, ``grep``, ``egrep``, ``cut`` etc + Usually when any of the above are used in global scope, it is to manipulate + a version or program name string. These should be avoided in favour of + pure ``bash`` constructs. The ``versionator`` eclass is often of use here. + See `Version Formatting Issues`_, `versionator.eclass-5`_ and `Bash Variable + Manipulation`_. + +``has_version``, ``best_version``, ``portageq`` + Calls to any of these globally indicates a serious problem. You must **not** + have metadata varying based upon system-dependent information -- see `The + Portage Cache`_. You should rewrite your ebuilds to correctly use + dependencies. + +``python``, ``perl`` etc + Ebuilds are ``bash`` scripts. Offloading anything you don't know how to do + in ``bash`` onto another language is not acceptable -- if nothing else, + because not all users will always have a full system when ebuilds are + sourced. + +QA Notice -- foo is setXid, dynamically linked and using lazy bindings +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Dynamically linked setXid applications should not use lazy bindings when linking +for security reasons. If this message is shown, you have a couple of options: + +* Modify the package's Makefile (or equivalent) to use ``-Wl,-z,now`` when + linking. This solution is preferred. +* Use ``append-ldflags`` (see `Adding Additional Flags`_) to add ``-Wl,-z,now``. + This will affect *all* binaries installed, not just the setXid ones. + +QA Notice -- ECLASS foo inherited illegally +''''''''''''''''''''''''''''''''''''''''''' + +All eclass inherits must be unconditional, or based purely upon static +machine-independent criteria (``PN`` and ``PV`` are most common here). See `The +Portage Cache`_. + +You may see this warning in situations where there is not actually any illegal +inheritance occurring. Most commonly: + +* When unmerging a package which was installed using an old portage version that + did not record inheritance. +* When working with eclasses in an overlay with a stale cache. See `Overlay and + Eclasses`_. +* When working with a stale portage cache. + +You should manually check against the rules described in `The Portage Cache`_ if +you see this notice locally. If you see this notice when working with a pure +``emerge sync`` over ``rsync`` setup, it is probably a genuine issue. + +.. Todo:: from vapier: + TEXTREL's ... binary files which contain text relocations ... see + 'prepstrip' for a full description unsafe files ... basically files that + are setid and writable by Other users i've added the following QA checks to + portage HEAD (no idea when they'll hit a release): Insecure RUNPATHs ... + binary files which have RUNPATH's encoded in them which are in +t + directories Executable stacks ... binary files whose stack is marked with + +x ... will bomb on amd64 for example + +Handling ``repoman`` Messages +----------------------------- + +.. Todo:: write me + +Handling Access Violations +-------------------------- + +Portage uses a sandbox for certain phases of the build process. This prevents a +package from accidentally writing outside 'safe' locations. See `Sandbox`_ for +details. + +If a package violates the sandbox, an error such as the following will be given +(assuming that the sandbox is enabled and working on the test system, which +should always be the case for developer boxes): :: + + --------------------------- ACCESS VIOLATION SUMMARY --------------------------- + LOG FILE = "/tmp/sandbox-app-misc_-_breakme-1-31742.log" + + open_wr: /big-fat-red-error + -------------------------------------------------------------------------------- + +The ``open_wr`` means the package tried to open for write a file that is not +inside write-permitted areas. In this case, the file in question is +``/big-fat-red-error``. + +Other error messages exist for read-restricted areas -- these are rarely used in +ebuilds. + +Access violations most commonly occur during the install phase. See +``src_install`` and `Install Destinations`_ for discussion. + +Sometimes problems can also occur with packages attempting to write to +``${HOME}``. To get around this, it is usually sufficient to trick the build +system into using a safer location. For example, the ``fluxbox`` menu generator +tries to work in ``${HOME}/.fluxbox`` -- to get around this, the following is +used: + +.. CODESAMPLE violation-1.ebuild + +In this situation, providing a fake home directory is all that is needed. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/appendices/common-problems/violation-1.ebuild b/appendices/common-problems/violation-1.ebuild new file mode 100644 index 0000000..20f05f9 --- /dev/null +++ b/appendices/common-problems/violation-1.ebuild @@ -0,0 +1,9 @@ +# Header. + +ebegin "Creating a menu file (may take a while)" +mkdir -p "${T}/home/.fluxbox" || die "mkdir home failed" +MENUFILENAME="${S}/data/menu" MENUTITLE="Fluxbox ${PV}" \ + CHECKINIT="no. go away." HOME="${T}/home" \ + ${S}/util/fluxbox-generate_menu -is -ds \ + || die "menu generation failed" +eend $? diff --git a/appendices/contributing/text.rst b/appendices/contributing/text.rst new file mode 100644 index 0000000..677d591 --- /dev/null +++ b/appendices/contributing/text.rst @@ -0,0 +1,192 @@ +Contributing to This Document +============================= + +Contributions for this document are highly welcomed. Whether you've found a typo +or have written an entire new section, the best way to get in touch is to `send +an email to plasmaroo <mailto:plasmaroo@gentoo.org>`_. + +The editor reserves the right to modify submissions as he sees fit. Any +substantial changes will of course be discussed with the submitter first -- +unless explicitly requested, minor typo corrections and formatting fixes will +not be discussed. + +This document is licenced under the `Creative Commons Attribution-ShareAlike +2.0 Licence <http://creativecommons.org/licenses/by-sa/2.0/>`_. If this is a +problem, don't submit anything. + +If you're looking for something to do, the automatically generated `Todo List`_ +might help. + +This document is produced using some scary Makefile hacks from `Restructured +Text (RST) <http://docutils.sourceforge.net/rst.html>`_ files. To view the +source for a page, append ``text.rst`` to the URL or check the link in the page +footer. If you'd rather just work with plain text, that's fine too -- the +formatting can be done by someone else. + +Quick Introduction to RST +------------------------- + +Take a look at `the source for this page <text.rst>`_ for the basic structure of +an RST document. + +RST Headings +'''''''''''' + +At the top of the page is a heading, which is underlined by a line of equals +signs. Within the page, normal headings use hyphens and subheadings use single +quotes. + +.. Important:: These heading conventions *must* be followed. Although standard + RST is more lenient regarding underline characters, the build system for this + document makes some assumptions. + +If subsubheadings are needed, use the caret character. Nothing actually uses +these yet -- it's probably better to restructure or split up your page if you +find yourself needing this. + +.. Warning:: Heading names must be unique *throughout the entire document*. Try + to pick long descriptive titles -- for example, 'Further Notes on Foo' rather + than 'Further Notes'. + +Currently, the colon character cannot be used in headings. If you really need to +use a colon, prod ciaranm and ask him to fix the build scripts. + +Inline Markup +''''''''''''' + +To make some *emphasised text*, surround it with ``*asterisks*``. To make some +**strongly emphasised text**, use ``**double asterisks**``. When typing ``code`` or +``filenames``, surround them with ````double backticks````. These characters can +be escaped using backslashes, like ``\`\`this\`\```. + +To link to another section of the document, type the section name inside +backticks and append an underscore, ```like this`_``. You can link to any +section in *any* page of the document in this manner. There are also link +targets for GLEPs defined automatically for you, so ```GLEP 23`_`` will produce +a link to `GLEP 23`_. + +To do an external hyperlink, use ```this format <http://example.com/>`_``. + +Lists +''''' + +To create a bullet list, use something like the following: :: + + + First + + Second + + * Subitem for second + * Another subitem for second + + + Third + +.. Note:: You **must** leave a blank line before and after a list (and each + sublevel in the list). A blank line between items is not necessary. + +You can use ``+``, ``*``, ``.`` and ``-`` for bullet characters as you prefer, +so long as you consistently use the same marker for the same level. + +To create a numbered list: :: + + 1. First + 2. Second + 3. Third + +Again, blank lines before and after the list are required. + +To create a key / value list: :: + + First Key + This text is the definition of first key. + + Second Key + And this text is the definition of second key. + +Code Blocks +''''''''''' + +Large code blocks are started with a double colon. Any subsequent lines which +are indented are taken to be part of the code block. To end a code block, use an +unindented line. For example: :: + + Here is an example code block: :: + + This is code. + This is still code. + There's no need to escape *dodgy markup* here. + + This is still code. + + This is no longer code. + +Tables +'''''' + +Tables in RST are tricky. Check `the main RST documentation +<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#tables>`_ if +you're feeling up to it. + +.. Todo:: Do we want to include some examples here? + +Special Paragraphs +'''''''''''''''''' + +To create a note, use the ``note`` directive: :: + + .. Note:: This is a note. Note the two dots, the space, the directive + type (in this case, Note), the lack of space and then the double + colons. Also see how continuations onto new lines are indented. + +There are also ``.. Warning::`` and ``.. Important::`` directives available. + +.. Note:: The RST specification includes various others, but we don't have + stylesheet rules defined for them. If there's anything you need from `the + full list + <http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions>`_, + ask to have stylesheet support added. + +The ``.. Todo::`` directive is a local hack that needs a patched docutils to +work. Feel free to use it, but be warned that it may not render correctly on +your system. + +Build System Hacks +'''''''''''''''''' + +There're a few sometimes-useful substitutions which are performed by the build +system. For example: :: + + .. CODESAMPLE filename.blah + +can be used to include a source file with generated syntax highlighting. It's +best to leave these to the editor -- they need some ``Makefile`` rules to back +them up. + +To include a list of 'children' for a table of contents, use: :: + + .. CHILDLIST + +Checking RST Text +----------------- + +To check RST source, use: :: + + rst2html.py --report=2 --halt=2 < text.rst + +You should ignore any warnings about missing link targets for GLEPs or link +references to headings in other documents -- these are handled automatically by +the build system. Similarly, ignore the lack of handling for ``.. Todo::`` and +the `build system hacks`_. + +Style Guidelines +---------------- + ++ This document is in British English. Submissions in other kinds of English are + welcome, but they may have their spelling corrected. ++ Third person should be used rather than first. ++ This is not a formal document. The writing style is intended to be + professional but readable. ++ When using in-sentence hyphens as punctuation -- like this -- use a space, + followed by two hyphens, followed by a space: ``--``. The build + system will automatically turn this into a proper Unicode long dash. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/appendices/editor-configuration/emacs/text.rst b/appendices/editor-configuration/emacs/text.rst new file mode 100644 index 0000000..450e957 --- /dev/null +++ b/appendices/editor-configuration/emacs/text.rst @@ -0,0 +1,38 @@ +Configuring ``emacs`` for UTF-8 +=============================== + +Emacs 21 has built-in Unicode support, and (fortunately) it supports +UTF-8 far better than UTF-16 and other variants. Some extensions to this +functionality are available in the package ``app-emacs/mule-ucs``, although +this is not necessary (and I would not recommend it unless absolutely +necessary, as the potential for unexpected bugs or quirky behaviour is +increased). + +In versions of Emacs below 21.3, and a non-UTF-8 locale is used when +opening a UTF-8 file, auto-detection of the character set is effectively +disabled and characters will be garbled. The UTF-8 character set can be +preferred with ``M-x prefer-coding-system`` and entering ``utf-8`` when +prompted. Otherwise, it is necessary to tell Emacs that a UTF-8 file is +being opened by prefixing the ``C-x C-f`` or ``C-x C-v`` command with +``C-x C-m c utf-8 RET``. As a diagnostic measure, the coding system currently +in use can be determined with ``C-h C <RET>``. + +Newer Emacs versions will autodetect the coding system for given text. + +If it is desired to prefer UTF-8 to the regular character set, +the following can be used inside of the Emacs startup file: + +:: + + (prefer-coding-system 'utf-8) + +For specifying coding system to use on a per-file basis, the +modify-coding-system function can be used. + +Further reading: + +* http://www.gnu.org/software/emacs/manual/emacs.html#Recognize%20Coding +* http://www.gnu.org/software/emacs/manual/emacs.html#Specify%20Coding +* http://www.emacswiki.org/cgi-bin/wiki/UnicodeEncoding +* http://www.emacswiki.org/cgi-bin/wiki/ChangingEncodings + diff --git a/appendices/editor-configuration/text.rst b/appendices/editor-configuration/text.rst new file mode 100644 index 0000000..dd43c2d --- /dev/null +++ b/appendices/editor-configuration/text.rst @@ -0,0 +1,13 @@ +Editor Configuration +==================== + +This section provides hints as to how to configue your text editor for working with ebuilds. + +.. Todo:: from vapier: add a section for nano ... users just have to copy + /etc/nanorc to ~/.nanorc and uncomment the sections for ebuilds + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/appendices/editor-configuration/vim/text.rst b/appendices/editor-configuration/vim/text.rst new file mode 100644 index 0000000..e5a2c62 --- /dev/null +++ b/appendices/editor-configuration/vim/text.rst @@ -0,0 +1,8 @@ +Configuring ``vim`` and ``gvim`` +================================ + +For full whitespace, character set, syntax and indent settings for ``vim`` and ``gvim``, emerge the ``app-vim/gentoo-syntax`` package. + +When fixing ebuilds with broken whitespace, the ``:retab!`` command may be of interest. The ! is required to replace spaces with tabs. + + diff --git a/appendices/editor-configuration/xemacs/text.rst b/appendices/editor-configuration/xemacs/text.rst new file mode 100644 index 0000000..819a144 --- /dev/null +++ b/appendices/editor-configuration/xemacs/text.rst @@ -0,0 +1,28 @@ +Configuring ``xemacs`` for UTF-8 +================================ + +First, you need to have built ``xemacs`` itself with ``USE=mule``. Then, the +``app-xemacs/mule-ucs`` package is needed. To autoload Unicode support, +you can add the following to your ``~/.xemacs/init.el``: + +:: + + (require 'un-define) + +If automatic character set detection on files is not working properly, +here are three commands that can help. + +* ``set-buffer-file-coding-system (C-x RET f)`` changes the coding + system for the current file. +* ``set-default-buffer-file-coding-system (C-x RET F)`` sets the default for + unsaved buffers and ASCII-looking files that have no obvious character + set markers for autodetection. +* ``universal-coding-system-argument (C-x RET c)`` + lets you set the coding system for the next command, so issuing + this from a dired window immediately before opening a problematic file + is a tactic that can be of use when autodetection gets things + pathologically wrong. + +The current coding system will be displayed near the left edge of the +status line. + diff --git a/appendices/further-reading/text.rst b/appendices/further-reading/text.rst new file mode 100644 index 0000000..2a3d424 --- /dev/null +++ b/appendices/further-reading/text.rst @@ -0,0 +1,29 @@ +Further Reading +=============== + +This section lists some recommended further reading. These are real +recommendations, not padding designed to make this document look important. + +Books +----- + +Mastering Regular Expressions + "Mastering Regular Expressions" by Jeffrey E. F. Friedl (O'Reilly, + ISBN 0-596-00289-0) is **the** book on regular expressions. Very readable and + devoid of the usual mathematical jargon that tends to fill up these kinds of + books. `Publisher's page <http://www.oreilly.com/catalog/regex2/>`__ + +Articles +-------- + +Making Packager-Friendly Software + `Making Packager-Friendly Software + <http://www.onlamp.com/pub/a/onlamp/2005/03/31/packaging.html>`__ by Julio M. + Merino Vidal describes various things that can be done by upstream software + providers to make life easy for the distribution people (that means you). + +How to Report Bugs Effectively + `How to Report Bugs Effectively <http://freshmeat.net/articles/view/149>`__ by + Simon Tatham is a good overview of effective bug reporting. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/appendices/man/Makefile.in b/appendices/man/Makefile.in new file mode 100644 index 0000000..3624292 --- /dev/null +++ b/appendices/man/Makefile.in @@ -0,0 +1,23 @@ +include make.common + +cache.man : cache.own-url + grep 'man$$' cache.own-url || ( \ + TERM=xterm \ + MANPAGER="tr '\267' '.' | col -b | \ + vim -f -u /etc/vim/vimrc -U NONE -i NONE \ + +':so ${TOPDIR}/tools/manpage.vim' +':w! /tmp/$@' \ + +':qa!' - " \ + man $$(sed -e 's,.*/\([^/]\+\)-\([^-]\+\)$$,\2,' < cache.own-url ) \ + $$(sed -e 's,.*/\([^/]\+\)-\([^-]\+\)$$,\1,' < cache.own-url ) && \ + sed -i -n -e '/^<pre>$$/,/^<\/pre>$$/p' /tmp/$@ && \ + sed -i -e 's/^/\t/' /tmp/$@ && \ + mv /tmp/$@ $@) + +cache.text : | $(TOPDIR)/skel/man.rst \ + $(wildcard text.rst) cache.own-url + [[ -f text.rst ]] && cp text.rst $@ || \ + sed -e 's,@TOPIC@,$(shell \ + sed -e 's,.*/\([^/]\+\)-\([^-]\+\)$$,\1,' < cache.own-url),' \ + -e 's,@SECTION@,$(shell \ + sed -e 's,.*/\([^/]\+\)-\([^-]\+\)$$,\2,' < cache.own-url),' \ + < $(TOPDIR)/skel/man.rst > $@ diff --git a/appendices/man/text.rst b/appendices/man/text.rst new file mode 100644 index 0000000..fc7f6b2 --- /dev/null +++ b/appendices/man/text.rst @@ -0,0 +1,11 @@ +Manual Pages +============ + +.. Note:: Some of these manual pages are taken from + ``app-portage/portage-manpages``. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/appendices/text.rst b/appendices/text.rst new file mode 100644 index 0000000..90edbae --- /dev/null +++ b/appendices/text.rst @@ -0,0 +1,10 @@ +Appendices +========== + +This section incorporates various auxiliary documents which may be useful as a +reference. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/archs/alpha/text.rst b/archs/alpha/text.rst new file mode 100644 index 0000000..824212c --- /dev/null +++ b/archs/alpha/text.rst @@ -0,0 +1,69 @@ +Arch Specific Notes -- ALPHA +============================ + +The ALPHA port uses the ``alpha`` keyword. It focuses upon HP (formerly Compaq +(formerly DEC)) hardware. This covers from ``ev4`` (known as 21064) through +``ev7z`` (known as 21364a). + +ALPHA Kernel and Userland ABIs +------------------------------ + +All ALPHA systems use a pure 64 bit kernel and a pure 64 bit userland. + +All ALPHA systems support both little and big endian -- however, Linux only uses +little endian. + +Additional ALPHA Keywording Requirements +---------------------------------------- + +It is generally expected that anyone who does keywording for ALPHA should be on +the ``alpha@`` alias. However the ALPHA Team is happy if maintainers keyword +their packages when they have access to ALPHA hardware, although the Team would +like to know about it. + +ALPHA Instruction Set and Performance Notes +------------------------------------------- + +There are six basic ALPHA instructions set standards: + +* ``ev4`` or ``ev45``. The ``ev4`` was the first ALPHA processor of the Alpha + family. It featured one integer pipeline and one floating-point pipeline. + The ``ev45`` is a modified ``ev4`` with double both Data and Instruction cache + (D-Cache and I-Cache respectively); it also featured a division optimization. +* ``ev5`` is an evolution of the ``ev45``. The number of pipelines was doubled + and the floating-point pipelines run in 9 stages rather than in 10. The + ``ev5`` supports 3 cache levels. +* ``ev56`` added the BWX extension to load/store data in 8 or 16 bit quanta. +* ``pca56`` added a new set, MVI (Motion Video Instructions), aimed to + accelerate video and audio calculations. +* ``ev6`` supports all extensions supported by the ``pca56`` and a new set, FIX, + meant to move data between integer and floating-point registers and for square + root. +* ``ev67`` is an evolution of the ``ev6``, in addition it supports a new set. + CIX adds instructions for counting and finding bits. + +When no ``-mcpu`` option is passed to ``gcc`` it defaults to the processor on +which the compiler was built. + +The ``-mieee`` flag **should** always be used unless you have a deep knowledge +of the ALPHA architecture, so the comments on `Not Filtering Variables`_ are +really important on ALPHA. + +Notes on ALPHA and PIC +---------------------- + +General `Position Independent Code`_ policy also applies to ALPHA. In fact, +ALPHA systems complain loudly if you try to link PIC and non-PIC code. Usually +this results in errors during the compilation aborting emerge. + +Contacting the ALPHA Team +------------------------- + +The ALPHA team can be contacted: + +* Via Bugzilla bugs assigned to ``alpha@`` +* Via email to the ``alpha@`` email alias +* Via email to the ``gentoo-alpha`` mailing list +* Via the ``#gentoo-alpha`` IRC channel on Freenode + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/archs/amd64/amd64-1.ebuild b/archs/amd64/amd64-1.ebuild new file mode 100644 index 0000000..6008264 --- /dev/null +++ b/archs/amd64/amd64-1.ebuild @@ -0,0 +1,14 @@ +# Header. + +inherit multilib + +src_compile() { + econf \ + --libdir=/usr/$(get_libdir) + + emake || die +} + +src_install() { + make DESTDIR=${D} install || die +} diff --git a/archs/amd64/amd64-2.c b/archs/amd64/amd64-2.c new file mode 100644 index 0000000..78a1847 --- /dev/null +++ b/archs/amd64/amd64-2.c @@ -0,0 +1,10 @@ +/* Header */ + +/* Common header file autogenerated by create_ml_includes in multilib.eclass */ +#ifdef __i386__ +#include <asm-i386/types.h> +#endif /* __i386__ */ + +#ifdef __x86_64__ +#include <asm-x86_64/types.h> +#endif /* __x86_64__ */ diff --git a/archs/amd64/amd64-3.ebuild b/archs/amd64/amd64-3.ebuild new file mode 100644 index 0000000..8ebae9d --- /dev/null +++ b/archs/amd64/amd64-3.ebuild @@ -0,0 +1,16 @@ +# Header. + +MULTILIB_ABIS="x86 amd64" +DEFAULT_ABI="amd64" + +CFLAGS_amd64="-m64" +LDFLAGS_amd64="-m elf_x86_64" +CHOST_amd64="x86_64-pc-linux-gnu" +CDEFINE_amd64="__x86_64__" +LIBDIR_amd64="lib64" + +CFLAGS_x86="-m32 -L/emul/linux/x86/lib -L/emul/linux/x86/usr/lib" +LDFLAGS_x86="-m elf_i386 -L/emul/linux/x86/lib -L/emul/linux/x86/usr/lib" +CHOST_x86="i686-pc-linux-gnu" +CDEFINE_x86="__i386__" +LIBDIR_x86="lib32" diff --git a/archs/amd64/text.rst b/archs/amd64/text.rst new file mode 100644 index 0000000..a7768da --- /dev/null +++ b/archs/amd64/text.rst @@ -0,0 +1,263 @@ +Arch Specific Notes -- AMD64/EM64T +================================== + +Position Independent Code Issues +-------------------------------- + +Gentoo Policy demands all shared objects to be compiled with ``-fPIC`` +in ``CFLAGS``. Since this is only a rule, you *can* break it on some arches. +You might never notice it. On AMD64, this is a necessity, if shared objects aren't +built with support for position independent code, the build process bails out +with an error message like this: :: + + foo.o: relocation R_X86_64_32 can not be used when making a shared + object; recompile with -fPIC + +How to fix -fPIC issues +~~~~~~~~~~~~~~~~~~~~~~~ + +There are several ways to enforce ``-fPIC`` on shared objects, each with its +pros and cons. + +``sed``'ing the Makefile +'''''''''''''''''''''''' + +Sometimes, a simple ``sed`` command is enough to fix it, however, the statements +normally aren't very readable and may fail when upstream changes the file. +Please verify that you only change the ``CFLAGS`` for *shared* objects, not for +the whole package. + +Patching ``Makefile.in``/``configure`` +'''''''''''''''''''''''''''''''''''''' + +This is more readable, and easier to send upstream. + +How **not** to fix -fPIC issues +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Do **not** patch the ``Makefile`` itself, since it is usually generated by the +``configure`` script and may vary heavily, so the patch could fail. Also, this +doesn't help upstream at all. + +Another bad idea is to (ab)use ``append-flags`` function from +``flag-o-matic.eclass``. Applying ``-fPIC`` on all objects will slow down the +binaries in a drastic way. + +Assembler Optimisation +---------------------- + +Modern x86 processors support special instruction sets like ``mmx``, ``sse``, +``SSE2`` and ``3DNow!``. AMD64 also provides support for them, but in most +cases, x86 assembler code is incompatible with AMD64 assembler. There are lots +of packages that provide support through USE flags for these instruction sets. +Originally, the USE flags were introduced to keep support for older processors +such as the Pentium I that can't handle such code. Currently, all AMD64s support the +same combination of extended instruction sets, so there is no reason to make +use of the mentioned USE flags. That's why these USE flags are hard-masked in +all AMD64-profiles. This doesn't mean we don't support the extensions +themselves, instead, we hard-enable them. + +The following USE flags are masked on AMD64: + +* mmx +* mmx2 +* sse +* sse2 +* 3dnow +* 3dnowext + +Multilib on AMD64 +----------------- + +The current AMD64 processors are able to natively run 32bit code on a 64bit +kernel. Therefore, you can run programs compiled for x86 in an amd64 environment. +However, 32bit applications need to be linked against 32bit libraries. Mixing +them won't work. For this reason the libraries are sorted, 32bit libraries normally +go to ``/lib32`` respectively ``/usr/lib32``, the 64bit ones normally to ``/lib64`` or +``/usr/lib64``. In a perfect world, you wouldn't have to read on. Unfortunately, +that's not the case, and so it's a bit more complicated. + +Multilib-Toolchain +~~~~~~~~~~~~~~~~~~ + +GCC +''' + +To generate 32bit code, we need a multilib-capable GCC. On other architectures, +this functionality is enabled with the USE flag ``multilib``. This is also true +for amd64 with the *pre*-2005.0 profiles. From 2005.0 on, you have to choose +whether you want multilib support or not by selecting the profile. Choose +``2005.0/no-multilib`` if you don't want it, all other profiles have the +``multilib`` USE flag masked, you're forced to it. With these profiles, GCC will +produce x86-code whenever you add ``-m32`` to its command line. Adding ``-m64`` +or omitting any bit-width option will default to producing 64bit code. + +glibc +''''' + +If you've chosen a multilib profile, glibc will be built twice, once 64bit and +once 32bit. This is because nearly every application links against glibc. +To understand how this is done in the ebuild, read `The ABI Variable`_. + +The ``emul-linux-x86-*`` packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As you read above, 32bit applications must be linked against 32bit libraries. +For that, we've put together the most used libraries and stuck them into the +so-called ``emul-linux-x86`` packages, which are located in the +``app-emulation`` category. + +emul-linux-x86-baselibs + Contains very basic libraries like zlib, pam, ncurses. + +emul-linux-x86-compat + Contains very old libraries for compatibility with binary-only programs. + +emul-linux-x86-glibc + Only used for compatibility reasons. This package is blocked by all + 2005.0 profiles. + +emul-linux-x86-gtklibs + The name says it -- GTK and its engines belong herein. + +emul-linux-x86-nvidia + Obsolete, ``media-video/nvidia-glx`` includes the 32bit library. + +emul-linux-x86-qtlibs + QT goes here. + +emul-linux-x86-sdl + libsdl and friends are here. + +emul-linux-soundlibs + alsa, libogg, just everything that is needed to get sound is located here. + +emul-linux-x86-xlibs + Contains the basic X libraries. + +These packages only provide pre-compiled libraries. Currently, the +archives are assembled manually, which is the main reason to keep the packages +as tidy as possible. Do not include libraries that aren't commonly used. + +.. Note:: The emul-packages might conflict with their native images, but only in + uncritical locations like ``/usr/share`` which are arch-independent anyway. + +``Libdir`` Links +~~~~~~~~~~~~~~~~ + +Currently, we provide several profiles, each with its own combination of ``libdir`` +configurations. + +========================== ========== ======= ======== +Profile lib32 lib lib64 +========================== ========== ======= ======== +2004.3 *l->emul* d64 *l->lib* +2004.3/lib64 *l->emul* *l->64* d64 +2005.0 d32 *l->64* d64 +2005.0/no-multilib d32 *l->64* d64 +2005.0/no-symlink d32 d d64 +2005.0/no-symlink/no-lib32 inexistant d32 d64 +========================== ========== ======= ======== + +d: Directory containing mixed-bit objects +dXX: Directory containing XXbit objects +l->foo: Link to foo + +To always get the right path, you should use the function ``$(get_libdir)`` from +``multilib.eclass``. It will always return the correct directory, on all arches. +And of course it also takes care of the ``ABI`` variable. + +The ``multilib-strict`` Feature +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Many Makefiles assume that their libraries should go to ``/usr/lib``, or +``$(prefix)/lib``. This assumption can cause a serious mess if ``/usr/lib`` +isn't a symlink to ``/usr/lib64``. To find the bad packages, we have a portage feature +called **multilib-strict**. It will prevent emerge from putting 64bit libraries +into anything other than ``(/usr)/lib64``. + +``multilib-strict`` currently doesn't check perl5, gcc, gcc-lib and eclipse-3, +this behaviour is controlled by the ``MULTILIB_STRICT_EXEMPT`` variable in +``make.profile``. + +How to fix ebuilds properly +''''''''''''''''''''''''''' + +In most cases, it's sufficient to use the ``$(get_libdir)`` function from +``multilib.eclass``: + +.. CODESAMPLE amd64-1.ebuild + +Some packages provide really bad Makefiles which hard-code ``/usr/lib``. Those +should be ``sed`` -ed or patched. Don't forget to let upstream know about your +modifications! + +Headers and Multilib +~~~~~~~~~~~~~~~~~~~~ + +Most C/C++ programs need standard header files like ``types.h``. Some of them +depend on architecture specific facts, e.g. ``types.h`` on the length +of machine words. To ensure that we can compile both 32bit and 64bit +applications and libraries, we treat ``/usr/include/asm`` a bit special. + +This is what ``/usr/include/asm/types.h`` looks like on a AMD64 box: + +.. CODESAMPLE amd64-2.c + +As you can see, this is just a wrapper that decides which file you need +depending on the the parameter ``-D`` given to gcc. You'll probably run into +some troubles if you try to compile something by hand and forget to append +``-D__x86_64__`` to your ``CFLAGS``. Of course, this is **not necessary** when +using portage. For an explanation, see the `The ABI Variable`_ section. + +The ABI Variable +~~~~~~~~~~~~~~~~ + +Whenever portage builds something on amd64, it has to decide whether it should +be 32bit or 64bit. As stated in `Headers and Multilib`_, the ``__i386__`` or +``__x86_64__`` respectively, is needed in ``CDEFINE``. Also, gcc has to know +what code it should produce, therefore ``-m32`` or ``-m64`` must be appended to +CFLAGS. This is done via ``profile.bashrc``. All you need to do if you want to +build a package 32bit is to set ``ABI=x86``. + +The details are shown in ``make.defaults``: + +.. CODESAMPLE amd64-3.ebuild + +Porting Notes +------------- + +Machine Word sizes +~~~~~~~~~~~~~~~~~~ + +On AMD64, some types differ in size from x86: + +=============== =========== ============ +Type x86 (ILP32) amd64 (LP64) +=============== =========== ============ +``char`` 1 byte 1 byte +``short`` 2 bytes 2 bytes +``int`` 4 bytes 4 bytes +``long`` **4 bytes** **8 bytes** +``long long`` 8 bytes 8 bytes +``pointer`` **4 bytes** **8 bytes** +``float`` 4 bytes 4 bytes +``double`` 8 bytes 8 bytes +``long double`` 16 bytes 16 bytes +=============== =========== ============ + +If you need an exact amount of space, don't use these types but the ``uXX`` and +``sXX`` ones provided by ``types.h``, where XX is the number of bits you need. +Switching to a type that is the same on both arches is not suggested since it's +not a clean solution and might cause problems with other arches. + +Casts +~~~~~ + +Many upstream developers assume that the length of a pointer is 4 bytes, which +can cause problems when programs do casts from ``void *`` to ``int`` and vice +versa. With GCC 3.4, this causes warnings, the compilation won't abort. If +you're lucky, your package works, but it's likely that you encounter +segmentation faults or strange behaviour. GCC 4.0 refuses to compile such code. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/archs/mips/text.rst b/archs/mips/text.rst new file mode 100644 index 0000000..bd8fce4 --- /dev/null +++ b/archs/mips/text.rst @@ -0,0 +1,73 @@ +Arch Specific Notes -- MIPS +=========================== + +The MIPS port uses the ``mips`` keyword. It focuses upon commonly available +hardware -- mainly SGI and Cobalt systems -- although various embedded and +special purpose boards are also supported. + +The ``mips`` keyword covers a huge range of architectures, CPUs and hardware, +from tiny embedded devices up to server class kit with many tens of CPUs. + +.. Note:: Terminology + ABI stands for "Application Binary Interface". It refers to issues like + calling conventions (which registers are used for passing parameters when + calling functions) and the size of data types. ISA stands for "Instruction + Set Architecture", and refers to the instructions available and the number + and types of registers for a given CPU. + +MIPS ABIs +--------- + +The ``o32`` ABI was a wonderful invention by SGI that was good at the time, but +later turned out to be a little bit short-sighted and inefficient. The ``n32`` +ABI corrects that problem by pretending to be 32 bit, whilst in reality being 64 +bit. ``n64`` is another 64 bit ABI, this time not pretending to be 32 bit, which +is therefore large, fat and yet very powerful. + +All of these ABIs can be both big and little endian, since MIPS CPUs come in +both flavours, although most hardware does not support both options. + +All of these ABIs are popular amongst various applications domains. None of them +actually work correctly. + +MIPS ISAs +--------- + +The most commonly seen MIPS ISAs are mips2, mips3, mips4, mips32 and mips64. If +you encounter a situation in which you need to know about the differences +between these, talk to the MIPS team. + +Not Dropping ``CFLAGS`` on MIPS +------------------------------- + +Because ``CFLAGS`` are sometimes used to specify ISA and ABI information, it is +vital that packages honour this setting. See `Not Filtering Variables`_. + +Additional MIPS Keywording Requirements +--------------------------------------- + +.. Note:: This section is in addition to the guidelines in `Keywording`_. It + discusses *additional* requirements for the MIPS architectures. + +For a package to have the ``~mips`` keyword added, the following additional +items must generally hold: + +* The package should work on both big and little endian systems, on both pure + 32 bit and pure 64 bit systems and on systems with differing kernel and + userland ABIs. + +It is generally expected that anyone who does keywording for MIPS should be on +the ``mips@`` alias. + +Contacting the MIPS Team +------------------------- + +The MIPS team can be contacted: + +* Via Bugzilla bugs assigned to ``mips@`` +* Via email to the ``mips@`` email alias +* Via email to the ``gentoo-mips`` mailing list +* Via the ``#gentoo-mips`` IRC channel on Freenode + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/archs/sparc/text.rst b/archs/sparc/text.rst new file mode 100644 index 0000000..c83cfb2 --- /dev/null +++ b/archs/sparc/text.rst @@ -0,0 +1,70 @@ +Arch Specific Notes -- SPARC +============================ + +The SPARC port uses the ``sparc`` keyword. It focusses mainly upon ``sun4u`` +hardware (Sun UltraSparc systems with ``v9`` CPUs), although ``sun4m`` (Sun 32 +bit hardware with ``v8`` and clones) is also sort-of supported. + +SPARC Kernel and Userland ABIs +------------------------------ + +``v9`` systems use a pure 64 bit kernel and a pure 32 bit userland. This can +cause portability problems when working with low level software if the kernel +does not provide working 32 bit compatibility interfaces. + +``v8`` systems use a pure 32 bit kernel and a pure 32 bit userland. + +All supported SPARC systems are big endian. + +Additional SPARC Keywording Requirements +---------------------------------------- + +.. Important:: This section is in addition to the guidelines in `Keywording`_. + It discusses *additional* requirements for the SPARC architecture. + +For a package to have the ``~sparc`` keyword added, the following additional +items must generally hold: + +* The package must have been tested by an arch team member (or someone with + permission from the arch team) *at least* on a ``v9`` system. Testing on + ``v8`` is encouraged but not required. + +It is generally expected that anyone who does keywording for SPARC should be on +the ``sparc@`` alias. + +SPARC Instruction Set and Performance Notes +------------------------------------------- + +There are three basic SPARC instruction set standards. + +* ``v7`` is the original instruction set used in very old hardware. Gentoo does + not ship ``v7`` capable stages, however a sufficiently crazy person could in + theory run Gentoo on a ``v7`` machine. +* ``v8`` is an extension of ``v7`` with added support for hardware integer + multiplication and division. Gentoo sparc32 (``sun4m``) stages are ``v8``. +* ``v9`` adds in 64 bit support and a large number of performance-enhancing + features. Gentoo sparc64 (``sun4u``) stages are ``v9``. + +In addition, individual CPU implementations have slight differences -- for +example, HyperSparc CPUs have relaxed requirements when it comes to scheduling +certain instructions. These are relatively minor differences. + +If ``gcc`` is invoked without any ``-mcpu`` parameter, it will generate ``v7`` +code. Depending upon the application, this can be anywhere up to five times +slower than ``v9`` code when running on an UltraSparc -- cryptographic and +graphics applications which make heavy use of integer multiplication and +division are especially badly hit. For this reason, the comments in `Not +Filtering Variables`_ are especially important on SPARC. + +Contacting the SPARC Team +------------------------- + +The SPARC team can be contacted: + +* Via Bugzilla bugs assigned to ``sparc@`` +* Via email to the ``sparc@`` email alias +* Via email to the ``gentoo-sparc`` mailing list +* Via the ``#gentoo-sparc`` IRC channel on Freenode + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/archs/text.rst b/archs/text.rst new file mode 100644 index 0000000..f6fc064 --- /dev/null +++ b/archs/text.rst @@ -0,0 +1,17 @@ +Arch Specific Notes +=================== + +This section provides a brief overview of various arch-specific issues. It is not +complete, and it is not a substitute for discussing any problems with the +relevant arch team. + +.. Note:: People who have worked with some other distributions may find Gentoo's + views on architecture support slightly unfamiliar. We do not follow Debian's + attempts to provide a standard set of packages at specific versions and install + it onto every platform -- rather, we simply attempt to provide whatever + happens to work best in any situation. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/archs/x86/text.rst b/archs/x86/text.rst new file mode 100644 index 0000000..3dce379 --- /dev/null +++ b/archs/x86/text.rst @@ -0,0 +1,10 @@ +Arch Specific Notes -- x86 +========================== + +Originally, it was assumed that all developers would have access to x86 hardware +and that x86 would be maintained by everyone. For this reason there is no team +for x86 of the kind that exists for other archs -- there *is* an ``x86@`` +Bugzilla alias, but it is generally only used for security bugs where the herd +has no members with x86 hardware. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/changelog/text.rst b/changelog/text.rst new file mode 100644 index 0000000..4b450d8 --- /dev/null +++ b/changelog/text.rst @@ -0,0 +1,78 @@ +Changes +======= + +20050529 ``ferdy`` + Added `Arch Specific Notes -- Alpha`_. + +20050527 ``ciaranm`` + Clarified some things in `Common Problems`_. Changed URL for `The + Portage Cache`_. + +20050526 ``ciaranm`` + Text for `Herds and Projects`_. + + Tidied up `Ebuild Revisions`_. + + More on `Filtering Variables`_. + + Added automatically generated `Todo List`_. + +20050525 ``flameeyes`` + `aclocal and m4 Files`_ section. + +20050522 ``flameeyes`` + `Working with PAM`_ section. + +20050522 ``ciaranm`` + Updated `Overlay`_, `The Portage Cache`_, `Eclass Writing Guide`_ with + more notes about eclasses in overlay. + + Moved `Init Scripts`_, `Completion Files`_, `Environment Files`_ from + `Miscellaneous Files`_ to the new `Tasks Reference`_ section. Moved + `Miscellaneous Files`_ to be under `Ebuild Writing`_. + + Added `Common Problems`_ section. + +20050521 ``ciaranm`` + Added `Licenses`_ section. + + Started `Arch Specific Notes`_ section. + +20050520 ``ciaranm`` + Added some more to 'How Autotools Work', renamed to `The Basics of + Autotools`_. + +20050519 ``ciaranm`` + Added `Contributing to This Document`_. + + Added some more to 'How Autotools Work'. + +20050518 ``fuzzyray`` + `RPM Sources`_ now has content. + +20050511 ``ciaranm`` + Fix naming in `Eclass Writing Guide`_. + +20050507 ``ciaranm`` + Improved 'How Autotools Work'. + + Added in note on ``einstall`` to the `Quickstart Ebuild Guide`_. + +20050507 ``hansmi`` + Clarify tab wording in `Here Documents`_. + +20050506 ``ciaranm`` + Added `tr -- Character Translation`_. + + Added `noblah USE Flags`_ and updated `Profiles use.mask File`_. + +20050505 ``ciaranm`` + Improved `pkg_nofetch`_ and `Restricting Automatic Mirroring`_. + + Added `glep31check -- UTF-8 Validation`_. + + Started a ChangeLog for keeping track of major user-facing changes. + Typo fixes, minor wording updates and build system alterations won't be + logged. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/error-handling/error-handling-1.ebuild b/ebuild-writing/error-handling/error-handling-1.ebuild new file mode 100644 index 0000000..317029c --- /dev/null +++ b/ebuild-writing/error-handling/error-handling-1.ebuild @@ -0,0 +1,3 @@ +# Header + +[[ -f foorc ]] && ( update_foorc || die "Couldn't update foorc!" ) diff --git a/ebuild-writing/error-handling/error-handling-2.ebuild b/ebuild-writing/error-handling/error-handling-2.ebuild new file mode 100644 index 0000000..7ac1b45 --- /dev/null +++ b/ebuild-writing/error-handling/error-handling-2.ebuild @@ -0,0 +1,5 @@ +# Header + +if [[ -f foorc ]] ; then + update_foorc || die "Couldn't update foorc!" +fi diff --git a/ebuild-writing/error-handling/error-handling-3.ebuild b/ebuild-writing/error-handling/error-handling-3.ebuild new file mode 100644 index 0000000..daf667f --- /dev/null +++ b/ebuild-writing/error-handling/error-handling-3.ebuild @@ -0,0 +1,3 @@ +# Header + +cat list | while read file ; do epatch ${file} ; done diff --git a/ebuild-writing/error-handling/error-handling-4.ebuild b/ebuild-writing/error-handling/error-handling-4.ebuild new file mode 100644 index 0000000..ff45221 --- /dev/null +++ b/ebuild-writing/error-handling/error-handling-4.ebuild @@ -0,0 +1,3 @@ +# Header + +while read file ; do epatch ${file} ; done < list diff --git a/ebuild-writing/error-handling/error-handling-5.ebuild b/ebuild-writing/error-handling/error-handling-5.ebuild new file mode 100644 index 0000000..af0133f --- /dev/null +++ b/ebuild-writing/error-handling/error-handling-5.ebuild @@ -0,0 +1,4 @@ +# Header + +bunzip2 ${DISTDIR}/${VIM_RUNTIME_SNAP} | tar xf +assert diff --git a/ebuild-writing/error-handling/text.rst b/ebuild-writing/error-handling/text.rst new file mode 100644 index 0000000..5e27eab --- /dev/null +++ b/ebuild-writing/error-handling/text.rst @@ -0,0 +1,72 @@ +Error Handling +============== + +Importance of Error Handling +---------------------------- + +Decent error handling is important because: + +* Errors must be detected *before* portage tries to install a broken or + incomplete package onto the live filesystem. If build failures aren't caught, + a working package could be unmerged and replaced with nothing. + +* When receiving bug reports, it is a lot easier to figure out what went wrong + if you know exactly which function caused the error, rather than just knowing + that, say, something somewhere in ``src_compile`` broke. + +* Good error handling and notification can help cut down on the number of bug + reports received for a package. + +The ``die`` Function +-------------------- + +The ``die`` function should be used to indicate a fatal error and abort the +build. Its parameters should be the message to display. + +Although ``die`` will work with no parameters, a short message should always be +provided to ease error identification. This is especially important when a +function can die in multiple places. + +Some portage-provided functions will automatically die upon failure. Others will +not. It is safe to omit the ``|| die`` after a call to ``epatch``, but not +``econf`` or ``emake``. + +Sometimes displaying additional error information beforehand can be useful. Use +``eerror`` to do this. See `Messages`_. + +``die`` and Subshells +--------------------- + +.. Warning:: ``die`` **will not work in a subshell**. + +The following code will not work as expected, since the ``die`` is inside a +subshell: + +.. CODESAMPLE error-handling-1.ebuild + +The correct way to rewrite this is to use an ``if`` block: + +.. CODESAMPLE error-handling-2.ebuild + +When using pipes, a subshell is introduced, so the following is unsafe: + +.. CODESAMPLE error-handling-3.ebuild + +Using input redirection (see `Abuse of cat`_) avoids this problem: + +.. CODESAMPLE error-handling-4.ebuild + +The ``assert`` Function and ``$PIPESTATUS`` +------------------------------------------- + +When using pipes, simple conditionals and tests upon ``$?`` will not correctly +detect errors occurring in anything except the final command in the chain. To get +around this, ``bash`` provides the ``$PIPESTATUS`` variable, and portage +provides the ``assert`` function to check this variable. + +.. CODESAMPLE error-handling-5.ebuild + +If you need the gory details of ``$PIPESTATUS``, see `bash-1`_. Most of the +time, ``assert`` is enough. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/examples/text.rst b/ebuild-writing/examples/text.rst new file mode 100644 index 0000000..4975720 --- /dev/null +++ b/ebuild-writing/examples/text.rst @@ -0,0 +1,26 @@ +Further Ebuild Examples +======================= + +We'll finish the ebuild writing guide with a few examples. These are real +packages that the author has worked on that may or may not be in the tree -- +most of these are fairly simple apps that illustrate certain points nicely. + +Writing a ``detox`` Ebuild +-------------------------- + +.. Todo:: write this + + +Writing an ``msort`` Ebuild +--------------------------- + +.. Todo:: write this + + +Writing a ``hilite`` Ebuild +--------------------------- + +.. Todo:: write this + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/file-format/header-sample.ebuild b/ebuild-writing/file-format/header-sample.ebuild new file mode 100644 index 0000000..07b119f --- /dev/null +++ b/ebuild-writing/file-format/header-sample.ebuild @@ -0,0 +1,5 @@ +# Header + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ diff --git a/ebuild-writing/file-format/text.rst b/ebuild-writing/file-format/text.rst new file mode 100644 index 0000000..561a70a --- /dev/null +++ b/ebuild-writing/file-format/text.rst @@ -0,0 +1,78 @@ +Ebuild File Format +================== + +An ebuild is a ``bash`` script which is executed within a special environment. Files +should be simple text files with a ``.ebuild`` extension. + +File Naming Rules +----------------- + +An ebuild should be named in the form ``name-version.ebuild``. + +The name section should contain only lowercase non-accented letters, the digits +0-9, hyphens, underscores and plus characters. Uppercase characters are strongly +discouraged, but technically valid. + +.. Note:: This is the same as `IEEE1003.1-2004-3.276`_, with the addition of the plus + character to keep gtk+ and friends happy. + +The version section is more complicated. It consists of one or more numbers +separated by full stop (or period, or dot, or decimal point) characters (eg +``1.2.3``, ``20050108``). The final number may have a single letter following it +(eg ``1.2b``). This letter should not be used to indicate 'beta' status -- +portage treats ``1.2b`` as being a later version than ``1.2`` or ``1.2a``. + +There can be a suffix to version indicating the kind of release. In the following table, what portage considers to be the 'lowest' version comes first. + +=============== =========================== +Suffix Meaning +=============== =========================== +``_alpha`` Alpha release (earliest) +``_beta`` Beta release +``_pre`` Pre release +``_rc`` Release candidate +(no suffix) Normal release +``_p`` Patch level +=============== =========================== + +Any of these suffixes may be followed by a non-zero positive integer. + +Finally, version may have a Gentoo revision number in the form ``-r1``. The initial +Gentoo version should have no revision suffix, the first revision should be +``-r1``, the second ``-r2`` and so on. See `Ebuild Revisions`_. + +Overall, this gives us a filename like ``libfoo-1.2.5b_pre5-r2.ebuild``. + +Ebuild Header +------------- + +All ebuilds committed to the tree should have a three line header immediately at +the start indicating copyright. This must be an exact copy of the contents of +``$(portageq portdir)/header.txt``. Ensure that the ``$Header: $`` line is not +modified manually -- CVS will handle this line specially. + +.. CODESAMPLE header-sample.ebuild + +Indenting and Whitespace +------------------------ + +Indenting in ebuilds must be done with tabs, one tab per indent level. Each tab +represents four spaces. Tabs should only be used for indenting, never inside +strings. + +Avoid trailing whitespace: repoman will warn you about this if your +ebuild contains trailing or leading whitespace (whitespace instead of +tabs for indentation) when you commit. + +Where possible, try to keep lines no wider than 80 positions. A 'position' is +generally the same as a character -- tabs are four positions wide, and multibyte +characters are just one position wide. + +Character Set +------------- + +All ebuilds (and eclasses, metadata files and ChangeLogs) must use the UTF-8 +character set. See `GLEP 31`_ for details, and `glep31check`_ for an easy way of +checking for validity. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/diagram.svg b/ebuild-writing/functions/diagram.svg new file mode 100644 index 0000000..5834bec --- /dev/null +++ b/ebuild-writing/functions/diagram.svg @@ -0,0 +1,71 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg viewBox="0 100 830 80" xmlns="http://www.w3.org/2000/svg" version="1.1"> + <desc>Ebuild Function Order</desc> + <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" /> + + <rect x="10" y="110" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="50" y="130">pkg_setup</text> + + <line x1="90" y1="125" x2="130" y2="125" stroke-width="2" stroke="black" /> + <line x1="130" y1="125" x2="122" y2="120" stroke-width="2" stroke="black" /> + <line x1="130" y1="125" x2="122" y2="130" stroke-width="2" stroke="black" /> + + <rect x="130" y="110" width="80" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="170" y="130">src_unpack</text> + + <line x1="210" y1="125" x2="250" y2="125" stroke-width="2" stroke="black" /> + <line x1="250" y1="125" x2="242" y2="120" stroke-width="2" stroke="black" /> + <line x1="250" y1="125" x2="242" y2="130" stroke-width="2" stroke="black" /> + + <rect x="250" y="110" width="80" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="290" y="130">src_compile</text> + + <line x1="330" y1="125" x2="370" y2="125" stroke-width="2" stroke="black" /> + <line x1="370" y1="125" x2="362" y2="120" stroke-width="2" stroke="black" /> + <line x1="370" y1="125" x2="362" y2="130" stroke-width="2" stroke="black" /> + + <path d="M 330 125 Q 350 125 350 137 Q 350 150 370 150 + L 450 150 Q 470 150 470 137 Q 470 125 490 125" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="370" y="110" width="80" height="30" + fill="#ccffcc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="410" y="130">src_test</text> + + <line x1="450" y1="125" x2="490" y2="125" stroke-width="2" stroke="black" /> + <line x1="490" y1="125" x2="482" y2="120" stroke-width="2" stroke="black" /> + <line x1="490" y1="125" x2="482" y2="130" stroke-width="2" stroke="black" /> + + <rect x="490" y="110" width="80" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="530" y="130">src_install</text> + + <line x1="570" y1="125" x2="610" y2="125" stroke-width="2" stroke="black" /> + <line x1="610" y1="125" x2="602" y2="120" stroke-width="2" stroke="black" /> + <line x1="610" y1="125" x2="602" y2="130" stroke-width="2" stroke="black" /> + + <rect x="610" y="110" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="130">pkg_preinst</text> + + <line x1="690" y1="125" x2="730" y2="125" stroke-width="2" stroke="black" /> + <line x1="730" y1="125" x2="722" y2="120" stroke-width="2" stroke="black" /> + <line x1="730" y1="125" x2="722" y2="130" stroke-width="2" stroke="black" /> + + <rect x="730" y="110" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="770" y="130">pkg_postinst</text> + + <path d="M 90 125 Q 110 125 110 142 Q 110 160 130 160 + L 570 160 Q 590 160 590 142 Q 590 125 610 125" + stroke-width="2" stroke="black" fill="none" /> + +</svg> + +<!-- vim: set ft=xml sw=4 sts=4 et : --> + diff --git a/ebuild-writing/functions/pkg_config/pkg_config-1.ebuild b/ebuild-writing/functions/pkg_config/pkg_config-1.ebuild new file mode 100644 index 0000000..1c74945 --- /dev/null +++ b/ebuild-writing/functions/pkg_config/pkg_config-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_config() +{ + eerror "This ebuild does not have a config function." +} diff --git a/ebuild-writing/functions/pkg_config/pkg_config-2.ebuild b/ebuild-writing/functions/pkg_config/pkg_config-2.ebuild new file mode 100644 index 0000000..458569a --- /dev/null +++ b/ebuild-writing/functions/pkg_config/pkg_config-2.ebuild @@ -0,0 +1,16 @@ +# Headers. + +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 +} diff --git a/ebuild-writing/functions/pkg_config/text.rst b/ebuild-writing/functions/pkg_config/text.rst new file mode 100644 index 0000000..9622da2 --- /dev/null +++ b/ebuild-writing/functions/pkg_config/text.rst @@ -0,0 +1,30 @@ +pkg_config +========== + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_config`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Run any special post-install configuration | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | manual | ++------------------+---------------------------------------------------+ + +Default ``pkg_config`` +---------------------- + +.. CODESAMPLE pkg_config-1.ebuild + +Example ``pkg_config`` +---------------------- + +Taken from the ``mysql`` ebuilds. Note the use of ``${ROOT}``. + +.. CODESAMPLE pkg_config-2.ebuild + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-1.ebuild b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-1.ebuild new file mode 100644 index 0000000..e417c9b --- /dev/null +++ b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-1.ebuild @@ -0,0 +1,12 @@ +# Headers + +pkg_nofetch() +{ + [ -z "${SRC_URI}" ] && return + + echo "!!! The following are listed in SRC_URI for ${PN}:" + for MYFILE in `echo ${SRC_URI}`; do + echo "!!! $MYFILE" + done + return +} diff --git a/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-2.ebuild b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-2.ebuild new file mode 100644 index 0000000..179f780 --- /dev/null +++ b/ebuild-writing/functions/pkg_nofetch/pkg_nofetch-2.ebuild @@ -0,0 +1,8 @@ +# Headers + +pkg_nofetch() { + einfo "Please download" + einfo " - ${P}-main.tar.bz2" + einfo " - ${P}-extras.tar.bz2" + einfo "from ${HOMEPAGE} and place them in ${DISTDIR}" +} diff --git a/ebuild-writing/functions/pkg_nofetch/text.rst b/ebuild-writing/functions/pkg_nofetch/text.rst new file mode 100644 index 0000000..41c5c99 --- /dev/null +++ b/ebuild-writing/functions/pkg_nofetch/text.rst @@ -0,0 +1,35 @@ +pkg_nofetch +=========== + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_nofetch`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Tell the user how to deal with fetch-restricted | +| | packages. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Enabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild | ++------------------+---------------------------------------------------+ + +Default ``pkg_nofetch`` +----------------------- + +.. CODESAMPLE pkg_nofetch-1.ebuild + +Example ``pkg_nofetch`` +----------------------- + +.. CODESAMPLE pkg_nofetch-2.ebuild + +Notes on ``pkg_nofetch`` +------------------------ + +This function is only triggered for packages which have ``RESTRICT="fetch"`` +(see `Restricting Automatic Mirroring`_) set, and only if one or more components +listed in ``SRC_URI`` are not already available in the ``distfiles`` directory. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/pkg_postinst/pkg_postinst-1.ebuild b/ebuild-writing/functions/pkg_postinst/pkg_postinst-1.ebuild new file mode 100644 index 0000000..f4c376a --- /dev/null +++ b/ebuild-writing/functions/pkg_postinst/pkg_postinst-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_postinst() +{ + return +} diff --git a/ebuild-writing/functions/pkg_postinst/pkg_postinst-2.ebuild b/ebuild-writing/functions/pkg_postinst/pkg_postinst-2.ebuild new file mode 100644 index 0000000..1fbc039 --- /dev/null +++ b/ebuild-writing/functions/pkg_postinst/pkg_postinst-2.ebuild @@ -0,0 +1,13 @@ +# Headers. + +pkg_postinst() { + if has_version '<x11-wm/fluxbox-0.9.10-r3' ; then + ewarn "You must restart fluxbox before using the [include] /directory/" + ewarn "feature if you are upgrading from an older fluxbox!" + ewarn " " + fi + einfo "If you experience font problems, or if fluxbox takes a very" + einfo "long time to start up, please try the 'disablexmb' USE flag." + einfo "If that fails, please report bugs upstream." + epause +} diff --git a/ebuild-writing/functions/pkg_postinst/text.rst b/ebuild-writing/functions/pkg_postinst/text.rst new file mode 100644 index 0000000..5f87394 --- /dev/null +++ b/ebuild-writing/functions/pkg_postinst/text.rst @@ -0,0 +1,35 @@ +pkg_postinst +============ + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_postinst`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Called after image is installed to ``${ROOT}`` | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild, binary | ++------------------+---------------------------------------------------+ + +Default ``pkg_postinst`` +------------------------ + +.. CODESAMPLE pkg_postinst-1.ebuild + +Sample ``pkg_postinst`` +----------------------- + +.. CODESAMPLE pkg_postinst-2.ebuild + +Common ``pkg_postinst`` Tasks +----------------------------- + +The most common use for ``pkg_postinst`` is to display post-install +informational messages or warnings. Note that ``has_version`` will operate on +the version that *was* installed, which can be useful for selective upgrade +messages. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/pkg_postrm/pkg_postrm-1.ebuild b/ebuild-writing/functions/pkg_postrm/pkg_postrm-1.ebuild new file mode 100644 index 0000000..83f20ca --- /dev/null +++ b/ebuild-writing/functions/pkg_postrm/pkg_postrm-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_postrm() +{ + return +} diff --git a/ebuild-writing/functions/pkg_postrm/pkg_postrm-2.ebuild b/ebuild-writing/functions/pkg_postrm/pkg_postrm-2.ebuild new file mode 100644 index 0000000..0abbd46 --- /dev/null +++ b/ebuild-writing/functions/pkg_postrm/pkg_postrm-2.ebuild @@ -0,0 +1,5 @@ +# Headers. + +pkg_postrm() { + fdo-mime_mime_database_update +} diff --git a/ebuild-writing/functions/pkg_postrm/text.rst b/ebuild-writing/functions/pkg_postrm/text.rst new file mode 100644 index 0000000..f878cc1 --- /dev/null +++ b/ebuild-writing/functions/pkg_postrm/text.rst @@ -0,0 +1,33 @@ +pkg_postrm +========== + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_postrm`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Called after a package is unmerged. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild, binary | ++------------------+---------------------------------------------------+ + +Default ``pkg_postrm`` +---------------------- + +.. CODESAMPLE pkg_postrm-1.ebuild + +Sample ``pkg_postrm`` +--------------------- + +.. CODESAMPLE pkg_postrm-2.ebuild + +Common ``pkg_postrm`` Tasks +--------------------------- + +``pkg_postrm`` is used to update symlinks, cache files and other generated +content after a package has been uninstalled. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/pkg_preinst/pkg_preinst-1.ebuild b/ebuild-writing/functions/pkg_preinst/pkg_preinst-1.ebuild new file mode 100644 index 0000000..107af7e --- /dev/null +++ b/ebuild-writing/functions/pkg_preinst/pkg_preinst-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_preinst() +{ + return +} diff --git a/ebuild-writing/functions/pkg_preinst/pkg_preinst-2.ebuild b/ebuild-writing/functions/pkg_preinst/pkg_preinst-2.ebuild new file mode 100644 index 0000000..32efaab --- /dev/null +++ b/ebuild-writing/functions/pkg_preinst/pkg_preinst-2.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_preinst() { + enewgroup foo + enewuser foo -1 /bin/false /dev/null foo +} diff --git a/ebuild-writing/functions/pkg_preinst/text.rst b/ebuild-writing/functions/pkg_preinst/text.rst new file mode 100644 index 0000000..b6d129e --- /dev/null +++ b/ebuild-writing/functions/pkg_preinst/text.rst @@ -0,0 +1,41 @@ +pkg_preinst +=========== + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_preinst`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Called before image is installed to ``${ROOT}`` | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild, binary | ++------------------+---------------------------------------------------+ + +Default ``pkg_preinst`` +----------------------- + +.. CODESAMPLE pkg_preinst-1.ebuild + +Sample ``pkg_preinst`` +---------------------- + +.. CODESAMPLE pkg_preinst-2.ebuild + +Common Tasks +------------ + +There are a few things that are often done in ``pkg_preinst``: + +* Adding users and groups -- see `Users and Groups`_ +* Modifying the install image for a particular system. This function allows + system-specific customisation to be done even when installing from a binary. + The most useful example is probably smart configuration file updating -- a + ``pkg_preinst`` could check a configuration file in ``${ROOT}/etc/`` and + create a smart updated version in ``${IMAGE}/etc/`` (see `Install + Destinations`_) rather than always trying to install the default configuration + file (remember `Configuration File Protection`_). + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/pkg_prerm/pkg_prerm-1.ebuild b/ebuild-writing/functions/pkg_prerm/pkg_prerm-1.ebuild new file mode 100644 index 0000000..0ad76df --- /dev/null +++ b/ebuild-writing/functions/pkg_prerm/pkg_prerm-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_prerm() +{ + return +} diff --git a/ebuild-writing/functions/pkg_prerm/pkg_prerm-2.ebuild b/ebuild-writing/functions/pkg_prerm/pkg_prerm-2.ebuild new file mode 100644 index 0000000..c6fc71a --- /dev/null +++ b/ebuild-writing/functions/pkg_prerm/pkg_prerm-2.ebuild @@ -0,0 +1,6 @@ +# Headers + +pkg_prerm() { + # clean up temp files + [[ -d "${ROOT}/var/tmp/foo" ]] && rm -rf "${ROOT}/var/tmp/foo" +} diff --git a/ebuild-writing/functions/pkg_prerm/text.rst b/ebuild-writing/functions/pkg_prerm/text.rst new file mode 100644 index 0000000..3984806 --- /dev/null +++ b/ebuild-writing/functions/pkg_prerm/text.rst @@ -0,0 +1,33 @@ +pkg_prerm +========= + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_prerm`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Called before a package is unmerged. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild, binary | ++------------------+---------------------------------------------------+ + +Default ``pkg_prerm`` +--------------------- + +.. CODESAMPLE pkg_prerm-1.ebuild + +Sample ``pkg_prerm`` +-------------------- + +.. CODESAMPLE pkg_prerm-2.ebuild + +Common ``pkg_prerm`` Tasks +-------------------------- + +``pkg_prerm`` is used to clean up any files that would otherwise prevent a clean +unmerge. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/pkg_setup/pkg_setup-1.ebuild b/ebuild-writing/functions/pkg_setup/pkg_setup-1.ebuild new file mode 100644 index 0000000..978ac66 --- /dev/null +++ b/ebuild-writing/functions/pkg_setup/pkg_setup-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +pkg_setup() +{ + return +} diff --git a/ebuild-writing/functions/pkg_setup/pkg_setup-2.ebuild b/ebuild-writing/functions/pkg_setup/pkg_setup-2.ebuild new file mode 100644 index 0000000..280dd90 --- /dev/null +++ b/ebuild-writing/functions/pkg_setup/pkg_setup-2.ebuild @@ -0,0 +1,17 @@ +# Headers. + +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 +} diff --git a/ebuild-writing/functions/pkg_setup/text.rst b/ebuild-writing/functions/pkg_setup/text.rst new file mode 100644 index 0000000..e949cf9 --- /dev/null +++ b/ebuild-writing/functions/pkg_setup/text.rst @@ -0,0 +1,26 @@ +pkg_setup +========= + ++------------------+---------------------------------------------------+ +| **Function** | ``pkg_setup`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Pre-build environment configuration and checks. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Disabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild, binary | ++------------------+---------------------------------------------------+ + +Default ``pkg_setup`` +--------------------- + +.. CODESAMPLE pkg_setup-1.ebuild + +Example ``pkg_setup`` +--------------------- + +.. CODESAMPLE pkg_setup-2.ebuild + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_compile/buildenv/cpu-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/cpu-sample.ebuild new file mode 100644 index 0000000..22c9261 --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/cpu-sample.ebuild @@ -0,0 +1,4 @@ +# + + # Can't use ultrasparc or ultrasparc3 code, drop to v9 + replace-cpu-flags ultrasparc ultrasparc3 v9 diff --git a/ebuild-writing/functions/src_compile/buildenv/filter-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/filter-sample.ebuild new file mode 100644 index 0000000..0e19943 --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/filter-sample.ebuild @@ -0,0 +1,5 @@ +# + + # -fomit-frame-pointer leads to nasty broken code on sparc thanks to a + # rather icky asm function + use sparc && filter-flags -fomit-frame-pointer diff --git a/ebuild-writing/functions/src_compile/buildenv/ldflags-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/ldflags-sample.ebuild new file mode 100644 index 0000000..6968a8e --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/ldflags-sample.ebuild @@ -0,0 +1,7 @@ +# + + # 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 diff --git a/ebuild-writing/functions/src_compile/buildenv/replace-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/replace-sample.ebuild new file mode 100644 index 0000000..c3c62e1 --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/replace-sample.ebuild @@ -0,0 +1,4 @@ +# + + # Seems to have issues with -Os, switch to -O2 + replace-flags -Os -O2 diff --git a/ebuild-writing/functions/src_compile/buildenv/strip-sample.ebuild b/ebuild-writing/functions/src_compile/buildenv/strip-sample.ebuild new file mode 100644 index 0000000..13b9628 --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/strip-sample.ebuild @@ -0,0 +1,4 @@ +# + + # Our app hates screwy flags + strip-flags diff --git a/ebuild-writing/functions/src_compile/buildenv/text.rst b/ebuild-writing/functions/src_compile/buildenv/text.rst new file mode 100644 index 0000000..d0718d7 --- /dev/null +++ b/ebuild-writing/functions/src_compile/buildenv/text.rst @@ -0,0 +1,78 @@ +Configuring Build Environment +============================= + +Sometimes it is necessary to manipulate certain aspects of the user's build +environment before running ``./configure``. The ``flag-o-matic`` eclass is the +best choice for manipulating ``CFLAGS``, ``LDFLAGS`` and suchlike. + +.. Note:: Except where otherwise specified, any function which operates on + ``CFLAGS`` also operates on ``CXXFLAGS``. + +Ebuilds must not simply ignore use ``CFLAGS`` -- see `Not Filtering Variables`_. + +Guidelines for Flag Filtering +----------------------------- + +If a package breaks with any reasonable ``CFLAGS``, it is best to filter the +problematic flag if a bug report is received. Reasonable ``CFLAGS`` are +``-march=``, ``-mcpu=``, ``-mtune=`` (depending upon arch), ``-O2``, ``-Os`` and +``-fomit-frame-pointer``. Note that ``-Os`` should usually be replaced with +``-O2`` rather than being stripped entirely. The ``-fstack-protector`` flag +should probably be in this group too, although our hardened team claim that this +flag never ever breaks anything... + +The ``-pipe`` flag doesn't affect the generated code, so it's not really +relevant here, but it's a sensible flag to have set globally. + +If a package breaks with other ``CFLAGS``, it is perfectly ok to close the bug +with a **WONTFIX** suggesting that the user picks more sensible global +``CFLAGS``. Similarly, if you suspect that a bug is caused by insane CFLAGS, an +**INVALID** resolution is suitable. + +All of the following assumes that the ebuild has an ``inherit flag-o-matic`` +line in the correct place. + +Simple Flag Stripping +--------------------- + +The ``filter-flags`` function can be used to remove a particular flag from +``CFLAGS``. Multiple arguments can be supplied; each is the name of a flag to +remove. + +.. CODESAMPLE filter-sample.ebuild + +There is a ``filter-ldflags`` function available which does the equivalent for +``LDFLAGS``. + +If a package is known to be very ``CFLAGS`` sensitive, the ``strip-flags`` +function will remove most flags, leaving only a minimal conservative set of +flags. + +.. CODESAMPLE strip-sample.ebuild + +Flag Replacement +---------------- + +To replace a flag with a different one, use ``replace-flags``. This is most +commonly used to replace ``-Os`` with ``-O2`` (or ``-O3`` with ``-O2`` if you +are feeling kind). + +.. CODESAMPLE replace-sample.ebuild + +There is also a special function named ``replace-cpu-flags`` for replacing CPU +(``-mtune``, ``-mcpu``, ``-march``) designation flags. The last argument is the +flag to use; previous arguments are the flags to be replaced. + +.. CODESAMPLE cpu-sample.ebuild + +Adding Additional Flags +----------------------- + +Sometimes it is necessary to add in additional ``CFLAGS`` or ``LDFLAGS``. The +``append-flags`` and ``append-ldflags`` functions can be used here. + +.. CODESAMPLE ldflags-sample.ebuild + +See `flag-o-matic.eclass Reference`_ for a full reference. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_compile/configure/text.rst b/ebuild-writing/functions/src_compile/configure/text.rst new file mode 100644 index 0000000..f717df3 --- /dev/null +++ b/ebuild-writing/functions/src_compile/configure/text.rst @@ -0,0 +1,30 @@ +Configuring a Package +===================== + +Many packages come with an autoconf-generated ``./configure`` script for +checking the build environment and configuring optional support for libraries. +The ``econf`` function should be used where possible -- this will provide +correct build and path specifications for a Gentoo environment. + +Often the configure script will try to automatically enable support for optional +components based upon installed packages. This must **not** be allowed to +happen. For example, if a user has ``perl`` installed but has ``USE="-perl"``, +packages with optional ``perl`` support must not link against ``perl``. This +automatic detection can usually be overridden using ``--enable-`` and +``--disable`` or ``--with-`` and ``--without-`` switches (but note that these +don't always work -- make sure these are tested properly). + +The ``use_enable`` and ``use_with`` utility functions should, where appropriate, +be used to generate these switches. + +.. CODESAMPLE use-sample.ebuild + +Sometimes the package's choice of name for the option will not exactly match the +name or case of the ``USE`` flag. This is *very* often the case with the ``X`` +flag. For these situations, there are two argument forms: + +.. CODESAMPLE use2-sample.ebuild + +To check for an unset ``USE`` flag, the ``use_enable !flag`` form can be used. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_compile/configure/use-sample.ebuild b/ebuild-writing/functions/src_compile/configure/use-sample.ebuild new file mode 100644 index 0000000..1127543 --- /dev/null +++ b/ebuild-writing/functions/src_compile/configure/use-sample.ebuild @@ -0,0 +1,21 @@ +# + +src_compile() { + # We have optional perl, python and ruby support + econf \ + $(use_enable perl ) \ + $(use_enable python ) \ + $(use_enable ruby ) \ + || die "Configure failed!" + + # ... +} + +src_compile() { + # Our package optional IPv6 support which uses --with rather than + # --enable / --disable + + econf $(use_with ipv6 ) || die "econf failed!" + + # ... +} diff --git a/ebuild-writing/functions/src_compile/configure/use2-sample.ebuild b/ebuild-writing/functions/src_compile/configure/use2-sample.ebuild new file mode 100644 index 0000000..fee17c3 --- /dev/null +++ b/ebuild-writing/functions/src_compile/configure/use2-sample.ebuild @@ -0,0 +1,16 @@ +# + +src_compile() { + # Our package has optional perl, python and ruby support + econf \ + $(use_enable perl perlinterp ) \ + $(use_enable python pythoninterp ) \ + $(use_enable ruby rubyinterp ) \ + || die "Configure failed!" + + # ... +} + +src_compile() { + econf $(use_with X x11 ) || die "econf failed!" +} diff --git a/ebuild-writing/functions/src_compile/default-sample.ebuild b/ebuild-writing/functions/src_compile/default-sample.ebuild new file mode 100644 index 0000000..cec696e --- /dev/null +++ b/ebuild-writing/functions/src_compile/default-sample.ebuild @@ -0,0 +1,10 @@ +# + +src_compile() { + if [ -x ./configure ]; then + econf + fi + if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then + emake || die "emake failed" + fi +} diff --git a/ebuild-writing/functions/src_compile/distutils/distutils-1.ebuild b/ebuild-writing/functions/src_compile/distutils/distutils-1.ebuild new file mode 100644 index 0000000..d2806bf --- /dev/null +++ b/ebuild-writing/functions/src_compile/distutils/distutils-1.ebuild @@ -0,0 +1,5 @@ +# Headers. + +inherit distutils + +DOCS="CHANGES" diff --git a/ebuild-writing/functions/src_compile/distutils/distutils-2.ebuild b/ebuild-writing/functions/src_compile/distutils/distutils-2.ebuild new file mode 100644 index 0000000..25cbfc9 --- /dev/null +++ b/ebuild-writing/functions/src_compile/distutils/distutils-2.ebuild @@ -0,0 +1,17 @@ +# Headers. + +src_compile() { + distutils_src_compile + # ... +} + +src_install() { + # From the docutils ebuild + distutils_src_install + cd ${S}/tools + for tool in *.py; do + newbin ${tool} docutils-${tool} + done + + # ... +} diff --git a/ebuild-writing/functions/src_compile/distutils/distutils-3.ebuild b/ebuild-writing/functions/src_compile/distutils/distutils-3.ebuild new file mode 100644 index 0000000..3115bcd --- /dev/null +++ b/ebuild-writing/functions/src_compile/distutils/distutils-3.ebuild @@ -0,0 +1,5 @@ +# Headers + +pkg_setup() { + distutils_python_tkinter +} diff --git a/ebuild-writing/functions/src_compile/distutils/text.rst b/ebuild-writing/functions/src_compile/distutils/text.rst new file mode 100644 index 0000000..54ae12f --- /dev/null +++ b/ebuild-writing/functions/src_compile/distutils/text.rst @@ -0,0 +1,42 @@ +Distutils +========= + +General overview +---------------- + +The python packaging system is known as "distutils", and the hallmark of a +python package using distutils is the presence of a ``setup.py`` file. +(One can think of the ``setup.py`` file as the python equivalent of a +Makefile.) Although distutils is straightforward to use by directly +running the ``setup.py`` with the appropriate arguments, the distutils +eclass makes the process much simpler (and dramatically lowers the chance of +sandbox violations). For example, for the ``dev-python/id3-py`` package the +body of the e-build (other than the header and URIs) could have been +written as: + +.. CODESAMPLE distutils-1.ebuild + +Any files listed in ``${DOCS}`` will be put in the docs directory when +installed. Note that older versions of the distutils eclass used +``${mydoc}`` instead, but the preferred variable is ``DOCS``. + +In practice, some tweaking is often required in the ``src_compile()`` or, +more commonly, in the ``src_install()`` steps, and the distutils eclass +provides ``distutils_src_compile()`` and ``distutils_src_install()`` +convenience functions: + +.. CODESAMPLE distutils-2.ebuild + +Tkinter (Tk) support +-------------------- + +Until portage gains the long-requested ability to depend on USE +flags, ebuild authors who package graphical python programs will +probably need to check at emerge-time whether or not python was +compiled with support for Tkinter. Since Tkinter requires Tk, +which requires X, default python builds do *not* include Tkinter. +It's easy enough to check: + +.. CODESAMPLE distutils-3.ebuild + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : diff --git a/ebuild-writing/functions/src_compile/make/getcc-sample.ebuild b/ebuild-writing/functions/src_compile/make/getcc-sample.ebuild new file mode 100644 index 0000000..c8eaf8e --- /dev/null +++ b/ebuild-writing/functions/src_compile/make/getcc-sample.ebuild @@ -0,0 +1,14 @@ +# + +inherit flag-o-matic toolchain-funcs + +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}:" build.sh \ + || die "sed Fix failed. Uh-oh..." + ./build.sh || die "Build failed!" +} diff --git a/ebuild-writing/functions/src_compile/make/text.rst b/ebuild-writing/functions/src_compile/make/text.rst new file mode 100644 index 0000000..2128e92 --- /dev/null +++ b/ebuild-writing/functions/src_compile/make/text.rst @@ -0,0 +1,40 @@ +Building +======== + +The ``emake`` function should be used to call ``make``. This will ensure that +the user's ``MAKEOPTS`` are used correctly. The ``emake`` function passes on +any arguments provided, so it can be used to make non-default targets (``emake +extras``), for example. Occasionally you might encounter a screwy non-autotools +``Makefile`` that explodes with ``emake``, but this is rare. + +Builds should be tested with various ``-j`` settings in ``MAKEOPTS`` to ensure +that the build parallelises properly. If a package does *not* parallelise +cleanly, it should be patched. + +If patching *really* isn't an option, ``emake -j1`` should be used. However, +when doing this please remember that you are seriously hurting build times for +many non-x86 users in particular. Forcing a ``-j1`` can increase build times +from a few minutes to an hour on some MIPS and SPARC systems. + +Fixing Compiler Usage +--------------------- + +Sometimes a package will try to use a bizarre compiler, or will need to be told +which compiler to use. In these situations, the ``tc-getCC()`` function from +``toolchain-funcs.eclass`` should be used. Other similar functions are available +-- these are documented in `toolchain-funcs.eclass-5`_. + +.. Note:: It is *not* correct to use the ``${CC}`` variable for this purpose. + +Sometimes a package will not use the user's ``${CFLAGS}``. This must be worked +around, as sometimes this variable is used for specifying critical ABI options. +In these cases, the build scripts should be modified (for example, with ``sed``) +to use ``${CFLAGS}`` correctly. + +.. CODESAMPLE getcc-sample.ebuild + +.. Note:: When using ``sed`` with ``CFLAGS``, it is not safe to use a comma or a + slash as a delimiter. The vapier-recommended character is a colon. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-1.ebuild b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-1.ebuild new file mode 100644 index 0000000..45d9d17 --- /dev/null +++ b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +src_compile() { + $(tc-getCC ) ${CFLAGS} -o ${PN} ${P}.c \ + || die "Compile failed!" +} diff --git a/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-2.ebuild b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-2.ebuild new file mode 100644 index 0000000..c38adb3 --- /dev/null +++ b/ebuild-writing/functions/src_compile/nobuildsystem/nobuildsystem-2.ebuild @@ -0,0 +1,11 @@ +# Headers. + +src_compile() { + CONFIG="-DLINUX -DGKRELLM2 -fPIC `pkg-config gtk+-2.0 --cflags`" + LIBS="`pkg-config gtk+-2.0 --libs` -shared" + OBJS="top_three2.o gkrelltop2.o" + + gcc -c $CONFIG $CFLAGS top_three.c -o top_three2.o || die + gcc -c $CONFIG $CFLAGS gkrelltop.c -o gkrelltop2.o || die + gcc $LIBS $CONFIG $CFLAGS -o gkrelltop2.so $OBJS || die +} diff --git a/ebuild-writing/functions/src_compile/nobuildsystem/text.rst b/ebuild-writing/functions/src_compile/nobuildsystem/text.rst new file mode 100644 index 0000000..7fed9c9 --- /dev/null +++ b/ebuild-writing/functions/src_compile/nobuildsystem/text.rst @@ -0,0 +1,19 @@ +No Build System +=============== + +Occasionally some really small packages are shipped simply as a single ``.c`` file. +In these circumstances, you can either write your own ``Makefile`` and ship it +with the source tarball, or just manually compile the thing from within the +ebuild. Here's an example, from ``app-misc/hilite``: + +.. CODESAMPLE nobuildsystem-1.ebuild + +Here's an example from ``x11-plugins/gkrelltop``, which ships with a +``Makefile`` that doesn't actually work: + +.. CODESAMPLE nobuildsystem-2.ebuild + +A possibly better alternative would be to patch the ``Makefile`` and send it +upstream. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_compile/sample-sample.ebuild b/ebuild-writing/functions/src_compile/sample-sample.ebuild new file mode 100644 index 0000000..12182c3 --- /dev/null +++ b/ebuild-writing/functions/src_compile/sample-sample.ebuild @@ -0,0 +1,13 @@ +# + +src_compile() { + use sparc && filter-flags -fomit-frame-pointer + append-ldflags -Wl,-z,now + + econf \ + $(use_enable ssl ) \ + $(use_enable perl perlinterp ) \ + || die "Configure failed!" + + emake || die "Make failed!" +} diff --git a/ebuild-writing/functions/src_compile/text.rst b/ebuild-writing/functions/src_compile/text.rst new file mode 100644 index 0000000..6e70721 --- /dev/null +++ b/ebuild-writing/functions/src_compile/text.rst @@ -0,0 +1,36 @@ +src_compile +=========== + ++------------------+---------------------------------------------------+ +| **Function** | ``src_compile`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Configure and build the package. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Enabled | ++------------------+---------------------------------------------------+ +| **Privilege** | user | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild | ++------------------+---------------------------------------------------+ + +Default ``src_compile`` +----------------------- + +.. CODESAMPLE default-sample.ebuild + +Sample ``src_compile`` +---------------------- + +.. CODESAMPLE sample-sample.ebuild + + +Build Processes +--------------- + +Depending upon the build process used by upstream, there are a number of +possible things that may be done during ``src_compile``: + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_install/src_install-1.ebuild b/ebuild-writing/functions/src_install/src_install-1.ebuild new file mode 100644 index 0000000..8f927a0 --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-1.ebuild @@ -0,0 +1,7 @@ +# Headers. + +src_install() +{ + return +} + diff --git a/ebuild-writing/functions/src_install/src_install-2.ebuild b/ebuild-writing/functions/src_install/src_install-2.ebuild new file mode 100644 index 0000000..c185882 --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-2.ebuild @@ -0,0 +1,6 @@ +# Headers. + +src_install() { + make DESTDIR="${D}" install || die "Install failed!" + dodoc README CHANGES +} diff --git a/ebuild-writing/functions/src_install/src_install-3.ebuild b/ebuild-writing/functions/src_install/src_install-3.ebuild new file mode 100644 index 0000000..d0abd9b --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-3.ebuild @@ -0,0 +1,3 @@ +# Headers. + + make DESTDIR="${D}" install || die "Install failed" diff --git a/ebuild-writing/functions/src_install/src_install-4.ebuild b/ebuild-writing/functions/src_install/src_install-4.ebuild new file mode 100644 index 0000000..ae493a2 --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-4.ebuild @@ -0,0 +1,3 @@ +# Headers. + + einstall || die "Install failed!" diff --git a/ebuild-writing/functions/src_install/src_install-5.ebuild b/ebuild-writing/functions/src_install/src_install-5.ebuild new file mode 100644 index 0000000..e827aff --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-5.ebuild @@ -0,0 +1,4 @@ +# Headers. + + dodir /usr/share/foo-styles/ + cp -R ${S}/ ${D}/ || die "Install failed!" diff --git a/ebuild-writing/functions/src_install/src_install-6.ebuild b/ebuild-writing/functions/src_install/src_install-6.ebuild new file mode 100644 index 0000000..d6cb68b --- /dev/null +++ b/ebuild-writing/functions/src_install/src_install-6.ebuild @@ -0,0 +1,50 @@ +# Headers. + +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 COPYING 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 +} diff --git a/ebuild-writing/functions/src_install/text.rst b/ebuild-writing/functions/src_install/text.rst new file mode 100644 index 0000000..3e61a65 --- /dev/null +++ b/ebuild-writing/functions/src_install/text.rst @@ -0,0 +1,72 @@ +src_install +=========== + ++------------------+---------------------------------------------------+ +| **Function** | ``src_install`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Install a package image to ``${D}`` | ++------------------+---------------------------------------------------+ +| **Sandbox** | Enabled | ++------------------+---------------------------------------------------+ +| **Privilege** | root | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild | ++------------------+---------------------------------------------------+ + +Default ``src_install`` +----------------------- + +.. CODESAMPLE src_install-1.ebuild + +Sample ``src_install`` +---------------------- + +.. CODESAMPLE src_install-2.ebuild + +Easy Installs +------------- + +Often, especially with autotools-powered packages, there is a ``Makefile`` +``install`` target which will honour the ``DESTDIR`` variable to tell it to +install to a non-root location. If possible, this should be used: + +.. CODESAMPLE src_install-3.ebuild + +.. Note:: ``make`` should be used over ``emake`` here. Most installs are not + designed to be parallelised. + +Sometimes this will end up installing a few things into strange places. If and +only if this is the case, the ``einstall`` function can be used: + +.. CODESAMPLE src_install-4.ebuild + +It is usually necessary to include additional ``dodoc`` statements for the +``README``, ``ChangeLog`` etc in these cases. + +Trivial Installs +---------------- + +For some packages with no ``Makefile`` that only install a small number of +files, writing a manual install using ``cp`` is the easiest option. For example, +to do a simple install of some (no compilation required) themes: + +.. CODESAMPLE src_install-5.ebuild + +Or sometimes a combination of ``insinto`` and ``doins`` (plus related functions +-- see `Install Functions Reference`_) -- the following is based upon the +``sys-fs/udev`` install: + +.. CODESAMPLE src_install-6.ebuild + +This is, of course, considerably harder to handle than a simple ``Makefile`` +driven install. + +Other Installs +-------------- + +Sometimes, there will be a ``Makefile`` that does not honour ``DESTDIR`` and a +non-trivial number of files to install. In these situations, it is best to patch +the ``Makefile`` and contact upstream explaining the situation to them. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_test/default-sample.ebuild b/ebuild-writing/functions/src_test/default-sample.ebuild new file mode 100644 index 0000000..17fc795 --- /dev/null +++ b/ebuild-writing/functions/src_test/default-sample.ebuild @@ -0,0 +1,22 @@ +# + +src_test() +{ + addpredict / + if make check -n &> /dev/null; then + echo ">>> Test phase [check]: ${CATEGORY}/${PF}" + if ! make check; then + hasq maketest $FEATURES && die "Make check failed. See above for details." + hasq maketest $FEATURES || eerror "Make check failed. See above for details." + fi + elif make test -n &> /dev/null; then + echo ">>> Test phase [test]: ${CATEGORY}/${PF}" + if ! make test; then + hasq maketest $FEATURES && die "Make test failed. See above for details." + hasq maketest $FEATURES || eerror "Make test failed. See above for details." + fi + else + echo ">>> Test phase [none]: ${CATEGORY}/${PF}" + fi + SANDBOX_PREDICT="${SANDBOX_PREDICT%:/}" +} diff --git a/ebuild-writing/functions/src_test/sample-sample.ebuild b/ebuild-writing/functions/src_test/sample-sample.ebuild new file mode 100644 index 0000000..b22bfa4 --- /dev/null +++ b/ebuild-writing/functions/src_test/sample-sample.ebuild @@ -0,0 +1,12 @@ +# + +src_compile() { + cd ${S}/src/testdir + + # Test 49 won't work inside a portage environment + sed -i -e 's~test49.out~~g' Makefile + + # Try to run the non-gui tests only + make test-nongui \ + || die "At least one test failed" +} diff --git a/ebuild-writing/functions/src_test/text.rst b/ebuild-writing/functions/src_test/text.rst new file mode 100644 index 0000000..4e37b24 --- /dev/null +++ b/ebuild-writing/functions/src_test/text.rst @@ -0,0 +1,64 @@ +src_test +======== + ++------------------+---------------------------------------------------+ +| **Function** | ``src_test`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Run pre-install test scripts. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Enabled | ++------------------+---------------------------------------------------+ +| **Privilege** | user | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild | ++------------------+---------------------------------------------------+ + +Default ``src_test`` +-------------------- + +.. CODESAMPLE default-sample.ebuild + +Sample ``src_test`` +------------------- + +.. CODESAMPLE sample-sample.ebuild + +Common ``src_test`` Tasks +------------------------- + +Often the default ``src_test`` 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: + +* Needing to use X. +* Needing to work with files which are disallowed by the sandbox. +* Requiring user input (``src_test`` must not be interactive). +* Requiring root privileges. + +Usually, removing the relevant test from the ``Makefile`` using ``sed`` or +skipping a particular ``make`` target is sufficient. + +.. Note:: ``emake`` should not be used for ``src_test`` -- trying to parallelise + tests unless the ``Makefile`` was specifically designed for this can cause all + sorts of strange problems. + +Try to ensure that tests work properly for your ebuild. A good test suite is +extremely helpful for arch maintainers. + +Skipping Tests +-------------- + +Sometimes it is necessary to skip tests entirely. This can be done using a dummy +``src_test`` function: + +.. CODESAMPLE true-sample.ebuild + +Another option would be to set ``RESTRICT="test"`` in the ebuild. + +.. 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. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_test/true-sample.ebuild b/ebuild-writing/functions/src_test/true-sample.ebuild new file mode 100644 index 0000000..6569c49 --- /dev/null +++ b/ebuild-writing/functions/src_test/true-sample.ebuild @@ -0,0 +1,6 @@ +# + +src_test() { + # Tests don't even remotely work inside portage + true +} diff --git a/ebuild-writing/functions/src_unpack/autopackage/text.rst b/ebuild-writing/functions/src_unpack/autopackage/text.rst new file mode 100644 index 0000000..dbefa92 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/autopackage/text.rst @@ -0,0 +1,27 @@ +Autopackage +=========== + +If a package is only supplied in autopackage format, you must **not** add it to +the tree, nor go anywhere near it. If a package is supplied in autopackage +format and some other sane standard format (for example a source tarball), use +the other format only. + +Autopackage packages are utterly unsuitable for Gentoo systems for a worryingly +large number of reasons: + +* To even *unpack* the package, you must run arbitrary code supplied by an + untrusted source. +* They install directly to the live filesystem. +* Their intrinsic dependency resolver is broken. +* They do not support the filesystem layout used by Gentoo. +* They do not support configuration protection. +* They can clobber arbitrary files on uninstall. +* The linking mechanism used is insufficiently flexible. +* The entire format is completely unportable and highly tied to x86 Linux + systems. + +Upstream are aware of these issues and have no desire to fix them -- indeed, +they pass off some of their most broken behaviour as 'features'. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_unpack/cvs/cvs-1.ebuild b/ebuild-writing/functions/src_unpack/cvs/cvs-1.ebuild new file mode 100644 index 0000000..ca4d64d --- /dev/null +++ b/ebuild-writing/functions/src_unpack/cvs/cvs-1.ebuild @@ -0,0 +1,19 @@ +# Headers. + +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 +} diff --git a/ebuild-writing/functions/src_unpack/cvs/cvs-2.ebuild b/ebuild-writing/functions/src_unpack/cvs/cvs-2.ebuild new file mode 100644 index 0000000..71f23c7 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/cvs/cvs-2.ebuild @@ -0,0 +1,14 @@ +# Headers. + +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. diff --git a/ebuild-writing/functions/src_unpack/cvs/text.rst b/ebuild-writing/functions/src_unpack/cvs/text.rst new file mode 100644 index 0000000..52d464f --- /dev/null +++ b/ebuild-writing/functions/src_unpack/cvs/text.rst @@ -0,0 +1,76 @@ +CVS Sources +=========== + +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. + +Disadvantages of CVS Sources +---------------------------- + +Note that CVS ebuilds should **not** generally be added to the tree (except +under ``package.mask``) for the following reasons: + +* Upstream CVS servers tend to be far less reliable than our mirroring system + (particularly if we're talking Sourceforge...). + +* CVS ebuilds create a very heavy server load -- 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. + +* Many users who are behind firewalls cannot use CVS. + +It is safer to make a snapshot instead. For example, ``vim`` snapshots are made +using: :: + + $ cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vim export -r HEAD vim + +Disadvantages of CVS Live Sources +--------------------------------- + +CVS ebuilds which work against ``HEAD`` rather than a specific date or revision +are even worse candidates for tree inclusion: + +* You can never be sure whether upstream's CVS will actually build at any given + point. + +* It is extremely difficult to track down bugs when you cannot install the same + version of a package as the reporter. + +* Many upstream packages tend to get upset if people aren't using a specific + released version. + +Using CVS Sources +----------------- + +To use a CVS source, ``cvs.eclass`` must be inherited, and then a number of +variables must be set. The following variables are often useful: + +================= ================ ======================== +Variable Purpose Example +================= ================ ======================== +``ECVS_SERVER`` Server and path ``"cvs.sourceforge.net:/cvsroot/vim"`` +``ECVS_MODULE`` Module ``"vim"`` +``ECVS_BRANCH`` Branch ``"HEAD"`` +``ECVS_AUTH`` Auth method ``"ext"`` +``ECVS_USER`` Username ``"anoncvs"`` +``ECVS_PASS`` Password ``""`` +``ECVS_TOPDIR`` Unpack location ``ECVS_TOP_DIR="${DISTDIR}/cvs-src/${ECVS_MODULE}"`` +================= ================ ======================== + +See the eclass itself for the full range of options. + +Then, to perform the actual checkout, use the ``cvs_src_unpack`` function. + +Here's a simple snippet, based upon the CVS options in ``vim.eclass``: + +.. CODESAMPLE cvs-1.ebuild + +Here's another approach, based upon the ``emacs-cvs`` ebuild, which relies upon +the default ``src_unpack`` provided in the eclass: + +.. CODESAMPLE cvs-2.ebuild + +This approach is simpler but less flexible. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_unpack/deb/text.rst b/ebuild-writing/functions/src_unpack/deb/text.rst new file mode 100644 index 0000000..e2f8edb --- /dev/null +++ b/ebuild-writing/functions/src_unpack/deb/text.rst @@ -0,0 +1,16 @@ +Deb Sources +=========== + +.. Todo:: write this. 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 / + + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/ebuild-writing/functions/src_unpack/epatch/epatch-1.ebuild b/ebuild-writing/functions/src_unpack/epatch/epatch-1.ebuild new file mode 100644 index 0000000..59c5e9e --- /dev/null +++ b/ebuild-writing/functions/src_unpack/epatch/epatch-1.ebuild @@ -0,0 +1,8 @@ +# Headers. + +src_unpack() { + unpack ${A} + cd ${S} + epatch ${FILESDIR}/${P}-destdir.patch + epatch ${FILESDIR}/${P}-parallel_build.patch +} diff --git a/ebuild-writing/functions/src_unpack/epatch/epatch-2.ebuild b/ebuild-writing/functions/src_unpack/epatch/epatch-2.ebuild new file mode 100644 index 0000000..5e9345d --- /dev/null +++ b/ebuild-writing/functions/src_unpack/epatch/epatch-2.ebuild @@ -0,0 +1,8 @@ +# Headers. + +src_unpack() { + unpack ${P}.tar.bz2 + cd ${S} + epatch ${DISTDIR}/${P}-suse-update.patch.bz2 + epatch ${FILESDIR}/${PV}-no-TIOCGDEV.patch +} diff --git a/ebuild-writing/functions/src_unpack/epatch/epatch-3.ebuild b/ebuild-writing/functions/src_unpack/epatch/epatch-3.ebuild new file mode 100644 index 0000000..42e0387 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/epatch/epatch-3.ebuild @@ -0,0 +1,8 @@ +# Headers. + +src_unpack() { + unpack ${A} + cd ${S} + EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \ + EPATCH_FORCE="yes" epatch +} diff --git a/ebuild-writing/functions/src_unpack/epatch/text.rst b/ebuild-writing/functions/src_unpack/epatch/text.rst new file mode 100644 index 0000000..287c45b --- /dev/null +++ b/ebuild-writing/functions/src_unpack/epatch/text.rst @@ -0,0 +1,69 @@ +Patching with ``epatch`` +======================== + +The canonical way of applying patches in ebuilds is to use ``epatch`` (from +``eutils.eclass``) inside ``src_unpack``. This function automatically handles +``-p`` levels, ``gunzip`` and so on as necessary. + +Note that distributing modified tarballs rather than a vanilla tarball and +patches is *highly* discouraged. + +Basic ``epatch`` Usage +---------------------- + +In its simplest form, ``epatch`` takes a single filename and applies that patch. +It will automatically ``die`` if the apply fails. The following is taken from +``app-misc/detox``: + +.. CODESAMPLE epatch-1.ebuild + +For larger patches, using ``mirror://gentoo/`` rather than ``files/`` is more +appropriate. In these situations, it is usually best to ``bzip2`` the patch in +question (as opposed to ``files/`` patches, which must **not** be compressed). +For example, from ``app-admin/showconsole``: + +.. CODESAMPLE epatch-2.ebuild + +Remember to add the patch to ``SRC_URI``. + +CVS Keyword Lines and Patches +''''''''''''''''''''''''''''' + +If your patch includes any changes to CVS ``$Id: $`` (or ``$Header: $``, or +``$Date: $``) lines, it cannot be distributed under ``files/``, since CVS will +clobber the patch when you commit. In these situations, either remove this hunk +of the patch manually, or mirror the file. + +Multiple Patches with ``epatch`` +-------------------------------- + +``epatch`` can also apply multiple patches (which can be selectively based upon +arch) from a single directory. This can be useful if upstream have a habit of +shipping severely broken releases that need dozens of patches. + +A simple example: + +.. CODESAMPLE epatch-3.ebuild + +Here, one of the ``SRC_URI`` components is a tarball containing many patches +with file extension ``.patch``. + +Variables which may be defined include: + +======================== ===================================================== +Variable Purpose +======================== ===================================================== +``EPATCH_SOURCE`` Specifies the directory in which ``epatch`` looks for + patches. +``EPATCH_SUFFIX`` File extension for patches. +``EPATCH_OPTS`` Default options to ``patch``. +``EPATCH_EXCLUDE`` List of patches to exclude. +``EPATCH_FORCE`` Force epatch to apply patches even if they do not + follow the canonical naming form (set to ``yes``). +======================== ===================================================== + +Bulk patches should be named in the form ``??_${ARCH}_foo.${EPATCH_SUFFIX}``. If +they are not, ``EPATCH_FORCE="yes"`` must be set. To apply a patch on all archs, +use ``all`` for the ``${ARCH}`` part. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_unpack/other-archive-formats/text.rst b/ebuild-writing/functions/src_unpack/other-archive-formats/text.rst new file mode 100644 index 0000000..b30d968 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/other-archive-formats/text.rst @@ -0,0 +1,28 @@ +Other Archive Formats +===================== + +There are a variety of other archive formats which you may encounter. + +Zip Files +--------- + +If a package is supplied as a ``.zip`` file, you should: + +* ``DEPEND`` upon ``app-arch/unzip`` +* Use ``unpack`` as normal + +Shar Files +---------- + +If a package is supplied as a ``.shar`` file, you should repackage it locally +into a ``.tar.bz2``. It may also be useful to ask upstream to use a friendlier +package format -- however, if they ship ``.shar``, chances are they haven't done +a release in at least ten years. + +RAR Files +--------- + +``.rar`` files must be repackaged locally into a ``.tar.bz2`` file. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_unpack/rpm/rpm-1.ebuild b/ebuild-writing/functions/src_unpack/rpm/rpm-1.ebuild new file mode 100644 index 0000000..4839e23 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/rpm/rpm-1.ebuild @@ -0,0 +1,3 @@ +# Headers. + +inherit rpm diff --git a/ebuild-writing/functions/src_unpack/rpm/rpm-2.ebuild b/ebuild-writing/functions/src_unpack/rpm/rpm-2.ebuild new file mode 100644 index 0000000..446bc6c --- /dev/null +++ b/ebuild-writing/functions/src_unpack/rpm/rpm-2.ebuild @@ -0,0 +1,8 @@ +# Headers. + +src_unpack () { + rpm_src_unpack ${A} + cd ${S} + + use ssl && epatch ${FILESDIR}/${PV}/${P}-ssl.patch +} diff --git a/ebuild-writing/functions/src_unpack/rpm/rpm-3.ebuild b/ebuild-writing/functions/src_unpack/rpm/rpm-3.ebuild new file mode 100644 index 0000000..d818c75 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/rpm/rpm-3.ebuild @@ -0,0 +1,39 @@ +# Headers. + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +inherit eutils versionator rpm + +MY_PV=$(replace_version_separator 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" +LICENSE="GPL-2 public-domain" +SLOT="0" +KEYWORDS="-*" +IUSE="" + +RESTRICT="nomirror" + +# Need to test if the file can be unpacked with rpmoffset and cpio +# If it can't then set: + +#DEPEND="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 () { + rpm_src_unpack ${A} + cd ${S} + EPATCH_SOURCE="${WORKDIR}" EPATCH_SUFFIX="patch" \ + EPATCH_FORCE="yes" epatch +} diff --git a/ebuild-writing/functions/src_unpack/rpm/text.rst b/ebuild-writing/functions/src_unpack/rpm/text.rst new file mode 100644 index 0000000..bbb4a53 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/rpm/text.rst @@ -0,0 +1,50 @@ +RPM Sources +=========== + +If a package is supplied as an .rpm file, you should: + +.. CODESAMPLE rpm-1.ebuild + + +If you don't need to do anything in the unpack phase, then you are finished as +the ``rpm.eclass`` exports a default ``src_unpack`` that will unpack the rpm +files. + +If you do need to apply patches then override ``src_unpack`` in a manner such +as: + +.. CODESAMPLE rpm-2.ebuild + +.. Note:: ``${A}`` can contain non-rpm files since the rpm eclass will call + the normal ``unpack`` function for files that are not in the rpm format. + + +Notes on Using ``rpm.eclass`` +----------------------------- + +There are two ways to unpack a rpm file -- using the ``rpmoffset`` program from +``rpm2targz`` and ``cpio``, or by using ``rpm2cpio`` from ``app-arch/rpm``. +Normally, for unpacking an rpm file, installing the entire rpm application is +overkill. Because of this, the eclass will only use ``rpm2cpio`` if ``rpm`` is +already installed on the system. If you want to force the eclass to only use +the rpm offset method, set ``USE_RPMOFFSET_ONLY=1``. + +Another issue that might arise is that ``rpmoffset`` and ``cpio`` are not able +to unpack the rpm file correctly. If this occurs, then you need to add +``app-arch/rpm`` to the ``DEPEND`` variable so that ``rpm2cpio`` will be used +instead. + +Example RPM Handling +-------------------- + +Here is an ebuild snippet that is based upon the fetchmail source rpm from SuSE +9.2. The ebuild snippet is complete enough to work with the ``ebuild unpack`` +command. The ebuild will download the source file from the OSU SuSE mirror, +unpack the file and apply the included patches. The filename should be +``suse-fetchmail-6.2.5.54.1.ebuild``. + +.. CODESAMPLE rpm-3.ebuild + +Completion of the ebuild left as exercise to the reader. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_unpack/src_unpack-1.ebuild b/ebuild-writing/functions/src_unpack/src_unpack-1.ebuild new file mode 100644 index 0000000..1cc9c25 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/src_unpack-1.ebuild @@ -0,0 +1,7 @@ +# Headers. + +src_unpack() { + if [ "${A}" != "" ]; then + unpack ${A} + fi +} diff --git a/ebuild-writing/functions/src_unpack/src_unpack-2.ebuild b/ebuild-writing/functions/src_unpack/src_unpack-2.ebuild new file mode 100644 index 0000000..21018ef --- /dev/null +++ b/ebuild-writing/functions/src_unpack/src_unpack-2.ebuild @@ -0,0 +1,11 @@ +# Headers. + +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!" +} diff --git a/ebuild-writing/functions/src_unpack/svn/svn-1.ebuild b/ebuild-writing/functions/src_unpack/svn/svn-1.ebuild new file mode 100644 index 0000000..13ab1a7 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/svn/svn-1.ebuild @@ -0,0 +1,6 @@ +# Headers. + +inherit subversion + +ESVN_REPO_URI="http://tao.uab.es/ion/svn/libtu/trunk" +ESVN_PROJECT="libtu-snapshot" diff --git a/ebuild-writing/functions/src_unpack/svn/text.rst b/ebuild-writing/functions/src_unpack/svn/text.rst new file mode 100644 index 0000000..dcb5c84 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/svn/text.rst @@ -0,0 +1,59 @@ +Subversion Sources +================== + +As with CVS, an eclass exists for working directly with upstream Subversion +repositories. See `subversion.eclass Reference`_ for a full list of functions +and variables. + +Disavantages of Subversion Sources +---------------------------------- + +Note that Subversion ebuilds should **not** generally be added to the tree +(except under ``package.mask``) for much the same reasons that live CVS ebuilds +should not (see `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. + +It is far safer to make a snapshot instead. For example, ``gentoo-syntax`` +snapshots could be (but aren't, because ciaranm is so lazy he automated it) +made using: :: + + $ svn export svn://svn.berlios.de/svnroot/repos/gentoo-syntax -r HEAD gentoo-syntax + +Disadvantages of Subversion Live Sources +---------------------------------------- + +Live Subversion ebuilds that work against ``HEAD`` have the same disadvantages +as Live CVS ebuilds. + +Using Subversion Sources +------------------------ + +To use a Subversion source, ``subversion.eclass`` must be inherited, and then at +least ``ESVN_REPO_URI`` must be set. The following variables are also noteworthy: + +=================== ========================================= ================ +Variable Purpose Example +=================== ========================================= ================ +``ESVN_REPO_URI`` Server and path (http, https, svn) ``"svn://svn.example.com/foobar/trunk"`` +``ESVN_STORE_DIR`` Unpack location ``ESVN_STORE_DIR="${DISTDIR}/svn-src"`` +``ESVN_PROJECT`` Project name of ebuild ``ESVN_PROJECT="${PN/-svn}"`` +``ESVN_BOOTSTRAP`` Bootstrap command or script ``ESVN_BOOTSTRAP="autogen.sh"`` +``ESVN_PATCHES`` Patches to apply during bootstrap ``ESVN_PATCHES="${FILESDIR}/*.patch"`` +=================== ========================================= ================ + +See the eclass itself and `subversion.eclass Reference`_ for the full range of +options. + +To perform the actual checkout, use the ``subversion_src_unpack`` function, +which calls both ``subversion_svn_fetch`` and ``subversion_bootstrap`` itself. + +Here is a simple snippet, based upon the Subversion options in +``litu-svn-20040902.ebuild``: + +.. CODESAMPLE svn-1.ebuild + +This approach is sufficient for most Subversion ebuilds. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/functions/src_unpack/text.rst b/ebuild-writing/functions/src_unpack/text.rst new file mode 100644 index 0000000..ba6060d --- /dev/null +++ b/ebuild-writing/functions/src_unpack/text.rst @@ -0,0 +1,47 @@ +src_unpack +========== + ++------------------+---------------------------------------------------+ +| **Function** | ``src_unpack`` | ++------------------+---------------------------------------------------+ +| **Purpose** | Extract source packages and do any necessary | +| | patching or fixes. | ++------------------+---------------------------------------------------+ +| **Sandbox** | Enabled | ++------------------+---------------------------------------------------+ +| **Privilege** | user | ++------------------+---------------------------------------------------+ +| **Called for** | ebuild | ++------------------+---------------------------------------------------+ + +Default ``src_unpack`` +---------------------- + +.. CODESAMPLE src_unpack-1.ebuild + +Sample ``src_unpack`` +--------------------- + +.. CODESAMPLE src_unpack-2.ebuild + +Unpacking Tarballs +------------------ + +The ``unpack`` function should be used to unpack tarballs, compressed files and +so on. Do not use ``tar``, ``gunzip`` etc. manually. + +The ``${A}`` variable contains all of the ``SRC_URI`` components, except for any +which are excluded by USE-based conditionals inside ``SRC_URI`` itself. If +multiple archives require unpacking in a particular order it is usually simpler +to avoid working with ``${A}``. + +``src_unpack`` Actions +---------------------- + +The following subsections cover different topics which often occur when writing +``src_unpack`` functions. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/src_unpack/tla/text.rst b/ebuild-writing/functions/src_unpack/tla/text.rst new file mode 100644 index 0000000..d8ce2a6 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/tla/text.rst @@ -0,0 +1,8 @@ +Arch Sources +============ + +.. Todo:: anyone want to write this? You can probably mostly copy the `CVS + Sources`_ and `Subversion Sources`_ chapters. -- ciaranm + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/functions/text.rst b/ebuild-writing/functions/text.rst new file mode 100644 index 0000000..b76c975 --- /dev/null +++ b/ebuild-writing/functions/text.rst @@ -0,0 +1,22 @@ +Ebuild Functions +================ + +When installing packages from source, the function call order is ``pkg_setup``, +``src_unpack``, ``src_compile``, ``src_test`` (optional, ``FEATURES="test"``), +``src_install``, ``pkg_preinst``, ``pkg_postinst``. When installing packages +from a binary, the function call order is ``pkg_setup``, ``pkg_preinst``, +``pkg_postinst``. + +.. figure:: diagram.png + :alt: ebuild function call order + +The ``pkg_prerm`` and ``pkg_postrm`` functions are called when uninstalling a +package. The ``pkg_config`` function is used for any special package +configuration -- it is only run when explicitly requested by the user. The +``pkg_nofetch`` function is used when a ``RESTRICT="fetch"`` package needs to +obtain some ``SRC_URI`` components. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/messages/messages-1.ebuild b/ebuild-writing/messages/messages-1.ebuild new file mode 100644 index 0000000..d567370 --- /dev/null +++ b/ebuild-writing/messages/messages-1.ebuild @@ -0,0 +1,7 @@ +# Headers + +pkg_postinst() { + einfo "You will need to set up your /etc/foo/foo.conf file before" + einfo "running foo for the first time. For details, please see the" + einfo "foo.conf(5) manual page." +} diff --git a/ebuild-writing/messages/messages-2.ebuild b/ebuild-writing/messages/messages-2.ebuild new file mode 100644 index 0000000..b7c000f --- /dev/null +++ b/ebuild-writing/messages/messages-2.ebuild @@ -0,0 +1,6 @@ +# Headers + +i=10 +while ((i--)) ; do + ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass" +done diff --git a/ebuild-writing/messages/messages-3.ebuild b/ebuild-writing/messages/messages-3.ebuild new file mode 100644 index 0000000..c1ab4e4 --- /dev/null +++ b/ebuild-writing/messages/messages-3.ebuild @@ -0,0 +1,8 @@ +# Headers + +ewarn "The 'frozbinate' function provided by eutils.eclass is deprecated" +ewarn "in favour of frozbinate.eclass, but this package has not been" +ewarn "updated yet. If this is a package from the main tree, please check" +ewarn "http://bugs.gentoo.org/ and file a bug if there is not one already." +ewarn "If this is your own package, please read the comments in the" +ewarn "frozbinate eclass for instructions on how to convert." diff --git a/ebuild-writing/messages/text.rst b/ebuild-writing/messages/text.rst new file mode 100644 index 0000000..53dd41d --- /dev/null +++ b/ebuild-writing/messages/text.rst @@ -0,0 +1,78 @@ +Messages +======== + +Sometimes it is necessary to display messages for the user. This can be for +errors, post-install help messages, pre-install warnings or simply to notify the +user of what's going on. It is considered good form to display a message +before any particularly long and silent task is carried out, for example (and it +also helps cut down on bogus "compiling foo froze!" bugs). + +.. Note:: It is a policy violation to use any of these functions to display a line + of characters (a banner header). The use of colours and special leading + characters provided by these functions is sufficient to make a message stand + out. + +In all cases, assume that the user's terminal is no wider than 79 columns, and +that the ``einfo``, ``ewarn`` and ``eerror`` functions will occupy 4 columns +with their fancy leading markers. + +Information Messages +-------------------- + +There are a number of functions available to assist here. The `echo` bash +internal is the simplest -- it simply displays its parameters as a message. + +The ``einfo`` function can be used to display an informational message which is +meant to 'stand out'. On a colour terminal, the message provided will be +prefixed with a green star. + +.. CODESAMPLE messages-1.ebuild + +Warning Messages +---------------- + +The ``ewarn`` function is similar, but displays a yellow star. This should be +used for warning messages rather than information. + +Error Messages +-------------- + +The ``eerror`` function displays a red star, and is used for displaying error +messages. It should almost always be followed by a ``die`` call. This function +is mainly used for displaying additional error details before bailing out. + +Important Messages +------------------ + +For *really* important messages, ``eutils.eclass`` provides ``ebeep`` and +``epause``. The former will beep a number of times, and the latter will pause +for several seconds to allow the user to read any messages. Both can be disabled +by the user -- you must **not** attempt to override the user's preference in +this. ``ebeep`` takes an optional parameter specifying how many times to beep. +``epause`` takes an optional parameter (which **must** be an exact whole number) +specifying for how long it should sleep. + +Do not abuse these functions -- better to save them for when things really are +important. + +See `Message Functions Reference`_ for a full list of functions. + +Good and Bad Messages +--------------------- + +Here is an example of a bad message: + +.. CODESAMPLE messages-2.ebuild + +* Displaying the same message repeatedly is excessive. +* The uppercase is excessive. +* The bad English looks unprofessional. +* The message will only confuse the end user and will not help them work out + whether they have a problem and how to solve it if they do. + +It would be better written as: + +.. CODESAMPLE messages-3.ebuild + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/misc-files/changelog/changelog b/ebuild-writing/misc-files/changelog/changelog new file mode 100644 index 0000000..96fa791 --- /dev/null +++ b/ebuild-writing/misc-files/changelog/changelog @@ -0,0 +1,10 @@ +# vim: set filetype=gentoo-changelog : + + *vim-6.3.068 (25 Mar 2005) + + 25 Mar 2005; Ciaran McCreesh <ciaranm@gentoo.org> +vim-6.3.068.ebuild: + New release. Fixes bug #79981, bug #81289, bug #83383, bug #83416, bug + #83565, bug #85758, upstream patches up to 6.3.068. + + 22 Mar 2005; Aron Griffis <agriffis@gentoo.org> vim-6.3-r4.ebuild: + Stable on alpha diff --git a/ebuild-writing/misc-files/changelog/text.rst b/ebuild-writing/misc-files/changelog/text.rst new file mode 100644 index 0000000..c54eff8 --- /dev/null +++ b/ebuild-writing/misc-files/changelog/text.rst @@ -0,0 +1,23 @@ +ChangeLog +========= + +.. _echangelog: .. + +The ``ChangeLog`` should be used to record all non-trivial changes to ebuilds, +*including keywording changes*. The `echangelog`_ tool should be used to create +``ChangeLog`` entries -- the format of a ``ChangeLog`` is now defined as +"whatever ``echangelog`` creates". + +You should include references to any relevant bugs. The standard format for +doing this is via the phrase ``bug #20600`` -- this format (with the hash sign +included) is recognised via `packages.gentoo.org <http://packages.gentoo.org/>`_ +and similar tools. When including user-submitted ebuilds or patches, you should +credit the user with their full name and email address (or whatever they use to +identify themselves on bugzilla -- some users prefer to be known only by a +nickname). + +A typical ``ChangeLog`` snippet might look like the following: + +.. CODESAMPLE changelog + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/misc-files/metadata/catmetadata.xml b/ebuild-writing/misc-files/metadata/catmetadata.xml new file mode 100644 index 0000000..0edec7e --- /dev/null +++ b/ebuild-writing/misc-files/metadata/catmetadata.xml @@ -0,0 +1,15 @@ +# Header + + <?xml version="1.0" encoding="UTF-8"?> + <!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> + <catmetadata> + <longdescription lang="en"> + The app-vim category contains plugins and syntax file + packages for the Vim text editor. + </longdescription> + <longdescription lang="de"> + Die Kategorie app-vim enthält Plugins und Syntax-Pakete + für den Vim Texteditor. + </longdescription> + </catmetadata> + diff --git a/ebuild-writing/misc-files/metadata/pkgmetadata.xml b/ebuild-writing/misc-files/metadata/pkgmetadata.xml new file mode 100644 index 0000000..deccd06 --- /dev/null +++ b/ebuild-writing/misc-files/metadata/pkgmetadata.xml @@ -0,0 +1,16 @@ +# Header + + <?xml version="1.0" encoding="UTF-8"?> + <!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> + <pkgmetadata> + <herd>vim</herd> + <maintainer> + <email>ciaranm@gentoo.org</email> + <name>Ciaran McCreesh</name> + </maintainer> + <longdescription lang="en"> + This package provides Vim syntax highlighting for Cfengine configuration + files, and automatic filetype detection for these files based upon + filename. + </longdescription> + </pkgmetadata> diff --git a/ebuild-writing/misc-files/metadata/text.rst b/ebuild-writing/misc-files/metadata/text.rst new file mode 100644 index 0000000..82c1699 --- /dev/null +++ b/ebuild-writing/misc-files/metadata/text.rst @@ -0,0 +1,47 @@ +Package and Category metadata.xml +================================= + +The ``metadata.xml`` file is used to specify additional data about a package or +category. + +Category Metadata +----------------- + +For categories, ``metadata.xml`` specifies a long description (in English and +optionally in other languages). The format is specified formally in `GLEP 34`_, +and the character set **must** be UTF-8 as specified by `GLEP 31`_. A typical +example: + +.. CODESAMPLE catmetadata.xml + + +When creating a new category, creating a ``metadata.xml`` file along with a +``<longdescription>`` in English is **mandatory**. Translations are handled by +any interested developer who speaks a language sufficiently well. + +The correct way to commit a *category* ``metadata.xml`` file is currently: :: + + xmllint --noout --valid metadata.xml + glep31check metadata.xml + cvs commit -m "blah" metadata.xml + +Package Metadata +---------------- + +For packages, ``metadata.xml`` can specify a long description and maintainer +information. If a long description in any language is provided, an English long +description must be present. A typical example might look like: + +.. CODESAMPLE pkgmetadata.xml + + +All new packages **must** include a ``metadata.xml`` file which specifies *at +least* a herd. If no herd is suitable, ``no-herd`` should be used, and at least +one maintainer **must** be listed -- however, if at all possible, find a herd +willing to be listed. + +Commits of package metadata files are handled by ``repoman``. You should ensure +that you have ``dev-libs/libxml2`` installed so that the XML can be validated. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/misc-files/patches/sample-patch.patch b/ebuild-writing/misc-files/patches/sample-patch.patch new file mode 100644 index 0000000..7408c3c --- /dev/null +++ b/ebuild-writing/misc-files/patches/sample-patch.patch @@ -0,0 +1,17 @@ +# Header + +# Detect Gentoo apache files properly. Gentoo bug 83565. + +--- runtime/filetype.vim.orig 2005-03-25 01:44:12.000000000 +0000 ++++ runtime/filetype.vim 2005-03-25 01:45:15.000000000 +0000 +@@ -93,6 +93,9 @@ + " Gentoo apache config file locations (Gentoo bug #76713) + au BufNewFile,BufRead /etc/apache2/conf/*/* setf apache + ++" More Gentoo apache config file locations (Gentoo bug #83565) ++au BufNewFile,BufRead /etc/apache2/{modules,vhosts}.d/*.conf setf apache ++ + " XA65 MOS6510 cross assembler + au BufNewFile,BufRead *.a65 setf a65 + + diff --git a/ebuild-writing/misc-files/patches/text.rst b/ebuild-writing/misc-files/patches/text.rst new file mode 100644 index 0000000..b0c754d --- /dev/null +++ b/ebuild-writing/misc-files/patches/text.rst @@ -0,0 +1,54 @@ +Patches +======= + +There is no fixed rule for patch naming. The following are guidelines only. + +Small patches (less than, say, a few KBytes) should be added to ``${FILESDIR}``. +If you anticipate having several patches, it often helps to create version +numbered subdirectories -- ``${FILESDIR}/${PV}/`` is conventional. Patches are +best named ``${P}-what-it-does.patch`` (or ``.diff``), where +``what-it-does`` is a two or three word description of what the patch is for. If +the patch is to fix a specific bug, it is often useful to add in the bug number +-- for example, ``vim-7.0-cron-vars-79981.patch``. If the patch is pulled from +upstream's CVS / SVN repository, it can help to include the revision number in +the patch name as a suffix to the version part -- +``fluxbox-0.9.12-3860-menu-backups.patch``. + +Patches included in ``${FILESDIR}`` should not be compressed. + +Larger patches should be mirrored. When mirroring patches, choosing a name that +will not cause conflicts is important -- the ``${P}`` prefix is highly +recommended here. Mirrored patches are often compressed with ``bzip2``. Remember +to list these patches in ``SRC_URI``. + +If a package requires many patches, even if they are individually small, it is +often best to create a patch tarball to avoid cluttering up the tree too much. + +Patch Descriptions +------------------ + +It is possible to include a description with a patch. This is often helpful when +others come to work with your packages, or, indeed when you come back to take a +look at your own package a few months later. Good things to include in comments +are: + +* What the patch actually does. Bug numbers are good here. +* Where the patch came from. Is it an upstream CVS/SVN pull, something from + Bugzilla, something you wrote? +* Whether the patch has been sent upstream. + +To include the description, simply insert it at the top of the patch file. The +``patch`` tool will ignore leading text until it finds something that looks like +it might be a 'start patching' instruction, so as long as each description line +starts with letters (rather than numbers, symbols or whitespace) there shouldn't +be a problem. Alternatively, prefix each description line with a hash (that's +``#``, or 'pound' to the USians) sign. It's also best to leave a single blank +line after the description and before the main patch. + +Here's a simple example (``023_all_vim-6.3-apache-83565.patch``) from the +``vim`` patch tarball: + +.. CODESAMPLE sample-patch.patch + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/misc-files/text.rst b/ebuild-writing/misc-files/text.rst new file mode 100644 index 0000000..63e2d5c --- /dev/null +++ b/ebuild-writing/misc-files/text.rst @@ -0,0 +1,9 @@ +Miscellaneous Files +=================== + +This section contains some notes on various miscellaneous files. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/text.rst b/ebuild-writing/text.rst new file mode 100644 index 0000000..afcffde --- /dev/null +++ b/ebuild-writing/text.rst @@ -0,0 +1,11 @@ +Ebuild Writing +============== + +This section describes how to write an ebuild. It covers the basic format of an +ebuild and the variables and functions available, and finishes off with some +general notes and extended examples. + +.. FULLCHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/use-conditional-code/text.rst b/ebuild-writing/use-conditional-code/text.rst new file mode 100644 index 0000000..adef71d --- /dev/null +++ b/ebuild-writing/use-conditional-code/text.rst @@ -0,0 +1,28 @@ +USE Flag Conditional Code +========================= + +Often a particular block of code must only be executed if a given USE flag is +set (or unset). For large blocks, ``if use foo`` is best, or for inverse tests +either ``if ! use foo`` or ``if use !foo`` can be used (the former is more +common and is recommended for readability). For single-statement conditions, the +``use foo && blah`` (or ``use foo || blah`` for negatives) form is often more +readable. + +The ``if [ "`use foo`" ]`` and ``if [ -n "`use foo`" ]`` forms which are +occasionally seen in older code must **not** be used. + +.. Note:: ``die`` will not work as expected within a subshell, so code in the + form ``use foo && ( blah ; blah )`` should be avoided in favour of a proper if + statement. See `die and Subshells`_. + +.. CODESAMPLE use-sample.ebuild + +For echoing content based upon a USE flag, there is often a better helper +function available. + +You must not rely upon ``use`` producing an output -- this no longer happens. +If you really need output displayed, use the ``usev`` function. The +``useq`` function is available for explicitly requesting no output. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/use-conditional-code/use-sample.ebuild b/ebuild-writing/use-conditional-code/use-sample.ebuild new file mode 100644 index 0000000..26f2fca --- /dev/null +++ b/ebuild-writing/use-conditional-code/use-sample.ebuild @@ -0,0 +1,21 @@ +# header + + # USE conditional blocks... + if use livecd ; then + # remove some extra files for a small livecd install + rm -fr ${vimfiles}/{compiler,doc,ftplugin,indent} + fi + + # Inverse USE conditional blocks... + if ! use cscope ; then + # the --disable-cscope configure arg doesn't quite work properly, + # so sed it out of feature.h if we're not USEing cscope. + sed -i -e '/# define FEAT_CSCOPE/d' src/feature.h || die "couldn't disable cscope" + fi + + # USE conditional statements... + use ssl && epatch ${FILESDIR}/${P}-ssl.patch + use sparc && filter-flags -fomit-frame-pointer + + # Inverse USE conditional statements... + use ncurses || epatch ${FILESDIR}/${P}-no-ncurses.patch diff --git a/ebuild-writing/users-and-groups/text.rst b/ebuild-writing/users-and-groups/text.rst new file mode 100644 index 0000000..d805533 --- /dev/null +++ b/ebuild-writing/users-and-groups/text.rst @@ -0,0 +1,51 @@ +Users and Groups +================ + +If your ebuild requires a user or group to be added for a daemon, for example, +this should be performed via the functions available in ``eutils.eclass``. +Regardless of whether you are adding a group or a user, this should be performed +in the ``pkg_setup`` function and **not** somewhere else: pkg_setup is sandbox-safe, +is called before the compile process so a build that requires the user to exist will +have it, and is also called for both binary and source packages. + +Adding Groups +------------- + +To add a group, use the ``enewgroup`` function: :: + + enewgroup <name> [uid] + +By default the next available group ID is selected. To set a specfic group ID, +pass it an extra argument to ``enewgroup``. + +.. Note:: Group IDs should rarely be hardcoded. If this is the case, you should + probably check first on gentoo-dev. + +Adding Users +------------ + +To add a user, use the ``enewuser`` function: :: + + enewuser <user> [uid] [shell] [homedir] [groups] [params] + +By default, both ``enewuser`` and ``enewgroup`` allocate the next available user +ID or group ID to the new user or group - if not, you explicitly have to specify +one. + +Arguments for ``enewuser`` must be passed in the order as shown above: if you do +not want to specify a fixed user ID however but do want to set a specific shell, +for example, use ``-1`` for the ``uid`` parameter. The same applies for any other +parameter where you want to keep the default setting. + +Groups for the ``groups`` argument should be separated by a comma (``,``) and +wrapped correctly, for example: :: + + enewuser frozd -1 -1 -1 "backup,frozd" + +Finally, any data left over for the ``params`` argument is passed directly to +useradd. + +.. Note:: User IDs should rarely be hardcoded. If this is the case, you should + probably check first on gentoo-dev. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/using-eclasses/devtodo.ebuild b/ebuild-writing/using-eclasses/devtodo.ebuild new file mode 100644 index 0000000..28386be --- /dev/null +++ b/ebuild-writing/using-eclasses/devtodo.ebuild @@ -0,0 +1,49 @@ +# Header + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +inherit eutils bash-completion flag-o-matic + +DESCRIPTION="A nice command line todo list for developers" +HOMEPAGE="http://swapoff.org/DevTodo" +SRC_URI="http://swapoff.org/files/${PN}/${P}.tar.gz" + +LICENSE="GPL-2" +SLOT="0" +KEYWORDS="alpha amd64 arm hppa ia64 mips ppc s390 sparc x86 ppc64" +IUSE="" + +RDEPEND=">=sys-libs/ncurses-5.2 + >=sys-libs/readline-4.1" +DEPEND="${RDEPEND}" + +src_unpack() { + unpack ${A} + cd ${S} + epatch ${FILESDIR}/${P}-gentoo.diff +} + +src_compile() { + einfo "Running autoreconf" + autoreconf -f -i || die "autoreconf failed" + replace-flags -O? -O1 + econf --sysconfdir=/etc/devtodo || die "econf failed" + emake || die "emake failed" +} + +src_install() { + make DESTDIR=${D} install || die "make install failed" + dodoc AUTHORS ChangeLog QuickStart README TODO doc/scripts.sh \ + doc/scripts.tcsh doc/todorc.example contrib/tdrec || die "dodoc failed" + dobashcompletion ${FILESDIR}/${PN}.bash-completion ${PN} +} + +pkg_postinst() { + echo + einfo "Because of a conflict with app-misc/tdl, the tdl symbolic link" + einfo "and manual page have been removed." + bash-completion_pkg_postinst +} + diff --git a/ebuild-writing/using-eclasses/text.rst b/ebuild-writing/using-eclasses/text.rst new file mode 100644 index 0000000..b8abf7d --- /dev/null +++ b/ebuild-writing/using-eclasses/text.rst @@ -0,0 +1,33 @@ +Using Eclassses +=============== + +An eclass is a collection (library) of functions or functionality that is shared +between packages. See `Eclass Writing Guide`_ for the full story on what +eclasses can do, how they work and how to write them, and `Eclass Reference`_ +for documentation on various commonly used eclasses. This section only explains +how to use an eclass which has already been written. + +The ``inherit`` Function +------------------------ + +To use an eclass, it must be 'inherited'. This is done via the ``inherit`` +function, which is provided by ``ebuild.sh``. The ``inherit`` statement must +come at the top of the ebuild, *before* any functions. Conditional inherits are +illegal (except where the inheritance criteria are cache-constant -- see `The +Portage Cache`_). + +After inheriting an eclass, its provided functions can be used as normal. Here's +``devtodo-0.1.18-r2.ebuild``, which uses three eclasses: + +.. CODESAMPLE devtodo.ebuild + +Note the ``inherit`` immediately after the header. + +The ``eutils`` eclass (see `eutils.eclass Reference`_) is needed to get the +``epatch`` function. The ``flag-o-matic`` eclass (see `flag-o-matic.eclass +Reference`_) is needed for ``replace-flags``, and the ``bash-completion`` eclass +(`bash-completion.eclass Reference`_) is used to handle the bash completion file +via ``dobashcompletion`` and ``bash-completion_pkg_postinst``. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/ebuild-writing/variables/text.rst b/ebuild-writing/variables/text.rst new file mode 100644 index 0000000..1d6c06c --- /dev/null +++ b/ebuild-writing/variables/text.rst @@ -0,0 +1,187 @@ +Variables +========= + +There are a number of special variables which must be set in ebuilds, and many +more which can optionally be specified. There are also some predefined variables +which are of use throughout the ebuild. + +Predefined Read-Only Variables +------------------------------ + +The following variables are defined for you. You must not attempt to set +them. + +============= ======================================================= +Variable Purpose +============= ======================================================= +``P`` Package name and version (excluding revision, if any), for example ``vim-6.3`` +``PN`` Package name, for example ``vim`` +``PV`` Package version (excluding revision, if any), for example ``6.3`` +``PR`` Package revision, or ``r0`` if no revision exists. +``PVR`` Package version and revision, for example ``6.3-r0``, ``6.3-r1``. +``PF`` Package name, version and revision, for example + ``vim-6.3-r1`` +``A`` All the source files for the package (excluding those + which are not available because of ``USE`` flags) +``CATEGORY`` Package's category, for example ``app-editors``. +``FILESDIR`` Path to the ebuild's ``files/`` directory, commonly used + for small patches and files. Value: + ``"${PORTDIR}/${CATEGORY}/${PN}/files"``. +``WORKDIR`` Path to the ebuild's root build directory. Value: + ``"${PORTAGE_TMPDIR}/portage/${PF}/work"``. +``T`` Path to a temporary directory which may be used by the + ebuild. Value: ``"${PORTAGE_TMPDIR}/portage/${PF}/temp"`` +``D`` Path to the temporary install directory. Value: + ``"${PORTAGE_TMPDIR}/portage/${PF}/image"`` +``ROOT`` Path to the root directory. When not using ``${D}``, + always prepend ``${ROOT}`` to the path. +============= ======================================================= + +Required Variables +------------------ + +The following variables must be defined by every ebuild. + +====================== ======================================================= +Variable Purpose +====================== ======================================================= +``DESCRIPTION`` A short (less than 80 characters) description of the + package's purpose. +``SRC_URI`` A list of source URIs for the package. Can contain + ``USE``-conditional parts, see `SRC_URI`_. +``HOMEPAGE`` Package's homepage +``KEYWORDS`` See `KEYWORDS`_ and `Keywording`_. +``SLOT`` The package's ``SLOT``. See `SLOT`_. +``LICENSE`` The package's licence, corresponding exactly (including + case) to a file in ``licenses/``. See `LICENSE`_. +``IUSE`` A list of all ``USE`` flags (excluding arch and auto + expand flags) used within the ebuild. See `IUSE`_. +====================== ======================================================= + +Optional Variables +------------------ + +Specifying the following variables is optional: + +====================== ======================================================= +Variable Purpose +====================== ======================================================= +``S`` Path to the temporary build directory, used by + ``src_compile`` and ``src_install``. Default: + ``"${WORKDIR}/${P}"``. Ebuilds should **not** provide a + value for this ebuild if it is the default. +``DEPEND`` A list of the package's build dependencies. See + `Dependencies`_. +``RDEPEND`` A list of the package's runtime dependencies. See + `Dependencies`_. +``PDEPEND`` A list of packages to be installed after the package + is merged. Should only be used where ``RDEPEND`` is not + possible. See `Dependencies`_. +``RESTRICT`` A space-delimited list of portage features to restrict. + Valid values are ``nostrip``, ``nomirror``, ``nouserpriv`` + and ``fetch``. See `ebuild-5`_ for details. +``PROVIDE`` Any virtuals provided by this package, for example + ``"virtual/editor virtual/emacs"``. +====================== ======================================================= + +SLOT +---- + +When slots are not needed, use ``SLOT="0"``. Do **not** use ``SLOT=""``, as +this will disable slotting for this package. + +KEYWORDS +-------- + +The only valid construct involving a ``*`` inside ``KEYWORDS`` is a ``-*``. Do +**not** use ``KEYWORDS="*"`` or ``KEYWORDS="~*"``. + +See `Keywording`_ for how to handle this variable. + +SRC_URI +------- + +Conditional Sources +''''''''''''''''''' + +Conditional source files based upon USE flags are allowed using the usual +``flag? ( )`` syntax. This is often useful for arch-specific code or for binary +packages -- downloading sparc binaries on ppc would be a waste of bandwidth. + +.. CODESAMPLE variables-1.ebuild + +When creating digests it may be necessary to have *all* SRC_URI components +downloaded. If you have ``FEATURES="cvs"`` set, portage should get this right, +although you may end up downloading more than necessary. + +If a ``USE_EXPAND`` variable is used to control whether certain optional +components are installed, the correct thing to do if the variable is unset is +generally to install *all* available components. + +.. CODESAMPLE variables-2.ebuild + +IUSE +---- + +Note that the ``IUSE`` variable is cumulative, so there is no need to specify +USE flags used only within inherited eclasses within the ebuild's IUSE. Also +note that it's really really broken in portage versions before 2.0.51. + +Arch USE flags (``sparc``, ``mips``, ``x86-fbsd`` and so on) should not be +listed. Neither should auto-expand flags (``linguas_en`` and so on). + +LICENSE +------- + +It is possible to specify multiple ``LICENSE`` entries, and entries which only +apply if a particular ``USE`` flag is set. The format is the same as for +``DEPEND``. See `GLEP 23`_ for details. + +Version Formatting Issues +------------------------- + +Often upstream's tarball versioning format doesn't quite follow Gentoo +conventions. Differences in how underscores and hyphens are used are +particularly common. For example, what Gentoo calls ``foo-1.2.3b`` may be +expecting a tarball named ``foo-1.2-3b.tar.bz2``. Rather than hard coding version +numbers, it is preferable to make a ``MY_PV`` variable and use that. The easy +way to do this, which should be used unless you are sure you know what you are +doing, is to use the ``versionator`` eclass: + +.. CODESAMPLE variables-3.ebuild + +This code has the advantage that it will carry on working even if upstream +switches to a format like ``foo-1.3-4.5.tar.bz2`` (yes, this really happens). + +It is also possible to use bash substitution to achieve the same effect (this is +how versionator works internally), but this is complicated, error prone and hard +to read. + +Some ebuilds use calls to ``sed``, ``awk`` and / or ``cut`` to do this. This +must *not* be done for any new code, and should be fixed to use either +versionator or bash substitution where possible. Global scope non-bash code is +highly discouraged. + +The ``versionator`` eclass can also be used to extract particular components +from a version string. See `versionator.eclass-5`_ and the eclass source code +for further documentation and examples. A brief summary of the functions +follows. + +==================================== ======================================== +Function Purpose +==================================== ======================================== +``get_all_version_components`` Split up a version string into its + component parts. +``get_version_components`` Get important version components, + excluding '.', '-' and '_'. +``get_major_version`` Get the major version. +``get_version_component_range`` Extract a range of subparts from a version + string +``get_after_major_version`` Get everything after the major version. +``replace_version_separator`` Replace a particular version separator. +``replace_all_version_separators`` Replace all version separators. +``delete_version_separator`` Delete a version separator. +``delete_all_version_separators`` Delete all version separators. +==================================== ======================================== + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/ebuild-writing/variables/variables-1.ebuild b/ebuild-writing/variables/variables-1.ebuild new file mode 100644 index 0000000..c396d3e --- /dev/null +++ b/ebuild-writing/variables/variables-1.ebuild @@ -0,0 +1,7 @@ +# Headers + +SRC_URI="http://example.com/files/${P}-core.tar.bz2 + x86? ( http://example.com/files/${P}/${P}-sse-asm.tar.bz2 ) + ppc? ( http://example.com/files/${P}/${P}-vmx-asm.tar.bz2 ) + sparc? ( http://example.com/files/${P}/${P}-vis-asm.tar.bz2 ) + doc? ( http://example.com/files/${P}/${P}-docs.tar.bz2 )" diff --git a/ebuild-writing/variables/variables-2.ebuild b/ebuild-writing/variables/variables-2.ebuild new file mode 100644 index 0000000..b7b2560 --- /dev/null +++ b/ebuild-writing/variables/variables-2.ebuild @@ -0,0 +1,10 @@ +# Headers + +SRC_URI="http://example.com/files/${P}-core.tar.bz2 + examplecards_foo? ( http://example.com/files/${P}-foo.tar.bz2 ) + examplecards_bar? ( http://example.com/files/${P}-bar.tar.bz2 ) + examplecards_baz? ( http://example.com/files/${P}-baz.tar.bz2 ) + !examplecards_foo? ( !examplecards_bar? ( !examplecards_baz? ( + http://example.com/files/${P}-foo.tar.bz2 + http://example.com/files/${P}-bar.tar.bz2 + http://example.com/files/${P}-baz.tar.bz2 ) ) )" diff --git a/ebuild-writing/variables/variables-3.ebuild b/ebuild-writing/variables/variables-3.ebuild new file mode 100644 index 0000000..0927589 --- /dev/null +++ b/ebuild-writing/variables/variables-3.ebuild @@ -0,0 +1,4 @@ +# Headers + +inherit versionator +MY_PV=$(replace_version_separator 2 '-') diff --git a/eclass-reference/bash-completion.eclass/text.rst b/eclass-reference/bash-completion.eclass/text.rst new file mode 100644 index 0000000..1563e31 --- /dev/null +++ b/eclass-reference/bash-completion.eclass/text.rst @@ -0,0 +1,25 @@ +``bash-completion.eclass`` Reference +==================================== + +The ``bash-completion`` eclass provides functions for installing contributed +bash-completion scripts. See `Completion Files`_ for how to write completion +scripts. + +================================= ====================================================== +Function Details +================================= ====================================================== +``dobashcompletion`` Install a bash completion file if and only if + the user has ``USE="bash-completion"``. If + ``BASH_COMPLETION_NAME`` is set, this will be used for + deciding the application name. Otherwise, the second + argument will be used (if present), or failing that, + ``${PN}``. +``bash-completion_pkg_postinst`` If the user has ``USE="bash-completion"``, + displays a message explaining how to activate + the completion for this package. +================================= ====================================================== + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + + diff --git a/eclass-reference/eutils.eclass/text.rst b/eclass-reference/eutils.eclass/text.rst new file mode 100644 index 0000000..fc17c9b --- /dev/null +++ b/eclass-reference/eutils.eclass/text.rst @@ -0,0 +1,46 @@ +``eutils.eclass`` Reference +=========================== + +The ``eutils`` eclass provides various useful functions. For full documentation, +see `eutils.eclass-5`_. + +========================= ====================================================== +Function Details +========================= ====================================================== +``epause`` See `Message Functions Reference`_ and `Messages`_ +``ebeep`` See `Message Functions Reference`_ and `Messages`_ +``gen_usr_ldscript`` Generate a linker script in ``/usr/lib`` for dynamic + libraries in ``/lib`` +``draw_line`` Draw a line the same length as the arguments. Do not + use this for messages. +``epatch`` Apply a patch (see `eutils.eclass-5`_ and `Patching + with epatch`_). +``have_NPTL`` True if we are using NPTL (threads). +``get_number_of_jobs`` Try to get the number of jobs to use when compiling. +``emktemp`` Replacement for ``mktemp``. +``egetent`` Wrapper for ``getent``. +``enewuser`` See `Users and Groups`_. +``enewgroup`` See `Users and Groups`_. +``edos2unix`` Fix one or more files to use Unix line endings. +``make_desktop_entry`` Create a ``.desktop`` file. Args are the binary, + the name, the icon, the application type and the startup + path. +``make_session_desktop`` Create a GDM session file. Arguments are the title and + the command. +``domenu`` Install a menu file. +``doicon`` Install an icon file. +``check_license`` Display a licence for the user to accept. Argument is + the licence to use. +``cdrom_get_cds`` See `eutils.eclass-5`_. +``cdrom_load_next_cd`` See `eutils.eclass-5`_. +``strip-linguas`` Make sure ``LINGUAS`` contains only allowed values. + See `Linguas`_. +``built_with_use`` Check that a package was built with a given USE flag + enabled. +``dopamd`` Install a pam auth config file. +``newpamd`` Install a pam auth config file (two arg version). +========================= ====================================================== + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/eclass-reference/fdo-mime.eclass/text.rst b/eclass-reference/fdo-mime.eclass/text.rst new file mode 100644 index 0000000..1d8a1a0 --- /dev/null +++ b/eclass-reference/fdo-mime.eclass/text.rst @@ -0,0 +1,16 @@ +``fdo-mime.eclass`` Reference +============================= + +The ``fdo-mime`` eclass provides functions for working with the FreeDesktop MIME +database. + +===================================== =========================================== +Function Details +===================================== =========================================== +``fdo-mime_desktop_database_update`` Updates the desktop database. Should be + called after modifying desktop entries. +``fdo-mime_mime_database_update`` Updates the MIME database. Should be + called after modifying MIME entries. +===================================== =========================================== + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/eclass-reference/flag-o-matic.eclass/text.rst b/eclass-reference/flag-o-matic.eclass/text.rst new file mode 100644 index 0000000..cbecc27 --- /dev/null +++ b/eclass-reference/flag-o-matic.eclass/text.rst @@ -0,0 +1,40 @@ +``flag-o-matic.eclass`` Reference +================================= + +The ``flag-o-matic`` eclass provides functions for manipulating ``CFLAGS``, +``CXXFLAGS``, ``LDFLAGS`` and similar. See `Configuring Build Environment`_ for +examples. + +========================================== ==================================== +Function Details +========================================== ==================================== +``filter-flags <flags>`` Removes any occurances of ``flags`` + in ``CFLAGS``, ``CXXFLAGS`` +``append-flags <flags>`` Appends ``flags`` to ``CFLAGS`` and + ``CXXFLAGS`` +``replace-flags <orig.flag> <new.flag>`` Replaces ``orig.flag`` (if present) + with ``new.flag`` in ``CFLAGS`` + and ``CXXFLAGS`` +``replace-cpu-flags <old.cpus> <new.cpu>`` Replaces ``-mtune=``, ``-mcpu=`` and + ``-march=`` flags with any of + ``old.cpus`` with ``new.cpu`` in + ``CFLAGS`` and ``CXXFLAGS`` +``is-flag <flag>`` Tests whether ``flag`` is a valid + flag with the current compiler +``strip-flags`` Removes all non-safe flags from + ``CFLAGS`` and ``CXXFLAGS`` +``strip-unsupported-flags`` Removes any flags in ``CFLAGS`` and + `CXXFLAGS`` which are not supported + by the active compiler +``get-flag <flag>`` Finds and echoes the value of the + specified flag +``filter-mfpmath <math types>`` Removes the specified maths types + from the fpmath specification (if + present) in ``CFLAGS`` and ``CXXFLAGS`` +``append-ldflags`` Appends the specified flags to ``LDFLAGS`` +``filter-ldflags <flags>`` Remove the specified flags (if + present) from ``LDFLAGS`` +========================================== ==================================== + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/eclass-reference/rpm.eclass/text.rst b/eclass-reference/rpm.eclass/text.rst new file mode 100644 index 0000000..421b1c3 --- /dev/null +++ b/eclass-reference/rpm.eclass/text.rst @@ -0,0 +1,31 @@ +``rpm.eclass`` Reference +======================== + +The ``rpm`` eclass provides RPM unpacking services for packages that must +extract a source tarball from an RPM. + +``rpm.eclass`` Variables +------------------------ + +======================== ====================================================== +Variables Details +======================== ====================================================== +``USE_RPMOFFSET_ONLY`` ``rpm_unpack`` normally will use rpm2cpio over + rpmoffset if both exist. If this variable is set to + 1, ``rpm_unpack`` will use rpmoffset. +======================== ====================================================== + +``rpm.eclass`` Functions +------------------------ + +======================== ====================================================== +Functions Details +======================== ====================================================== +``rpm_unpack`` *<file>* Unpacks an RPM. Behaves in the same fashion as + ``unpack`` (see `Unpacking Tarballs`_). +``rpm_src_unpack`` Default ``src_unpack`` that loops through ``${A}`` + calling ``rpm_unpack`` for RPM's and ``unpack`` for + everything else. +======================== ====================================================== + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/eclass-reference/subversion.eclass/text.rst b/eclass-reference/subversion.eclass/text.rst new file mode 100644 index 0000000..b681f71 --- /dev/null +++ b/eclass-reference/subversion.eclass/text.rst @@ -0,0 +1,51 @@ +``subversion.eclass`` Reference +=============================== + +The ``subversion`` eclass provides functions that enable the ebuild author to +create 'live' ebuilds that fetch the program's sources from a subversion +repository. + +See `Subversion Sources`_ for an introduction. + +``subversion.eclass`` Variables +------------------------------- + +==================== ==================================================== +Variables Details +==================== ==================================================== +``ESVN_REPO_URI`` URI from which the sources will be fetched. Valid + protocols: http, https, and svn. At a minimum, this + variable *must* be set. +``ESVN_STORE_DIR`` Location fetched sources will be kept. Defaults to + ``${DISTDIR}/svn-src``. +``ESVN_FETCH_CMD`` Command used for initial checkout. Defaults to + ``svn checkout``. +``ESVN_UPDATE_CMD`` Command used for updating sources. Defaults to + ``svn update``. +``ESVN_PROJECT`` Name of the project. Defaults to ``${PN/-svn}``. +``ESVN_BOOTSTRAP`` Name of bootstrap script. This variable is empty by + default. './' is automatically prepended. +``ESVN_PATCHES`` List of patches to apply prior to fetching the + sources. In addition to literal filenames, you may + also use globbing such as \*.diff. This variable is + empty by default. +==================== ==================================================== + +``subversion.eclass`` Functions +------------------------------- + +========================== ============================================== +Functions Details +========================== ============================================== +``subversion_src_unpack`` The default ``src_unpack`` that runs + ``subversion_svn_fetch`` and + ``subversion_bootstrap``. +``subversion_svn_fetch`` Fetches the program's sources from the URI + specified by ``ESVN_REPO_URI`` and copies to + ``${S}``. +``subversion_bootstrap`` Applies any patches specified by + ``ESVN_PATCHES`` and executes the bootstrap + script specified by ``ESVN_BOOTSTRAP``. +========================== ============================================== + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/eclass-reference/text.rst b/eclass-reference/text.rst new file mode 100644 index 0000000..4ebc342 --- /dev/null +++ b/eclass-reference/text.rst @@ -0,0 +1,10 @@ +Eclass Reference +================ + +This section provides a reference for some of the more commonly used eclasses. +Note that most eclasses have an accompanying manual page -- see `Manual Pages`_. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/eclass-writing/eclass-writing-1.ebuild b/eclass-writing/eclass-writing-1.ebuild new file mode 100644 index 0000000..7954c32 --- /dev/null +++ b/eclass-writing/eclass-writing-1.ebuild @@ -0,0 +1,26 @@ +# Headers. + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +# +# Original Author: Ciaran McCreesh <ciaranm@gentoo.org> +# Purpose: install macos .app files to the relevant location. +# +# Bugs to osx@gentoo.org +# + +ECLASS="macos-app" +INHERITED="$INHERITED $ECLASS" + +# domacosapp: install a macos .app file. Usage is 'domacosapp file' or +# 'domacosapp file newfile'. + +domacosapp() { + [[ -z "${1}" ]] && die "usage: domacosapp <file> <new file>" + if useq ppc-macos ; then + insinto /Applications + newins "$1" "${2:-${1}}" || die "Failed to install ${1}" + fi +} diff --git a/eclass-writing/eclass-writing-2.ebuild b/eclass-writing/eclass-writing-2.ebuild new file mode 100644 index 0000000..3d742ff --- /dev/null +++ b/eclass-writing/eclass-writing-2.ebuild @@ -0,0 +1,9 @@ +# Headers. + +ECLASS="fnord" +INHERITED="$INHERITED $ECLASS" +EXPORT_FUNCTIONS src_compile + +fnord_src_compile() { + do_stuff || die +} diff --git a/eclass-writing/eclass-writing-3.ebuild b/eclass-writing/eclass-writing-3.ebuild new file mode 100644 index 0000000..0935dfe --- /dev/null +++ b/eclass-writing/eclass-writing-3.ebuild @@ -0,0 +1,9 @@ +# Headers. + +inherit fnord.eclass + +src_compile() { + do_pre_stuff || die + fnord_src_compile + do_post_stuff || die +} diff --git a/eclass-writing/eclass-writing-4.ebuild b/eclass-writing/eclass-writing-4.ebuild new file mode 100644 index 0000000..df10d0c --- /dev/null +++ b/eclass-writing/eclass-writing-4.ebuild @@ -0,0 +1,28 @@ +# Headers. + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +# Original Author: Ciaran McCreesh <ciaranm@gentoo.org> +# Purpose: Demonstration of EXPORT_FUNCTIONS. Defines simple wrappers for the +# (hypothetical) 'jmake' build system and a default src_compile. + +ECLASS="jmake" +INHERITED="$INHERITED $ECLASS" +EXPORT_FUNCTIONS src_compile + +DEPEND=">=sys-devel/jmake-2" + +jmake-configure() { + jmake configure --prefix=/usr "$@" +} + +jmake-build() { + jmake dep && jmake build "$@" +} + +jmake_src_compile() { + jmake-configure || die "configure failed" + jmake-build || die "build failed" +} diff --git a/eclass-writing/text.rst b/eclass-writing/text.rst new file mode 100644 index 0000000..8990522 --- /dev/null +++ b/eclass-writing/text.rst @@ -0,0 +1,125 @@ +Eclass Writing Guide +==================== + +This section provides a brief introduction to eclass authoring. + +.. Important:: You should reread the `Overlay and Eclasses`_ and `The Portage + Cache`_ sections before continuing. + +Purpose of Eclasses +------------------- + +An eclass is a collection of code which can be used by more than one ebuild. At +the time of writing, all eclasses live in the ``eclass/`` directory in the tree. +Roughly speaking, there are three kinds of eclass: + +* Those which provide common functions which are used by many ebuilds (for + example, ``eutils``, ``versionator``, ``cvs``, ``bash-completion``) +* Those which provide a basic build system for many similar packages (for + example, ``vim-plugin``, ``kde``) +* Those which handle one or a small number of packages with complex build + systems (for example, ``vim``, ``toolchain``, ``kernel-2``) + +Adding and Updating Eclasses +---------------------------- + +Before committing a new eclass to the tree, it should be emailed to the +gentoo-dev mailing list with a justification and a proposed implementation. Do +not skip this step -- sometimes a better implementation or an alternative which +does not require a new eclass will be suggested. + +Before updating ``eutils`` or a similar widely used eclass, it is best to email +the gentoo-dev list. It may be that your proposed change is broken in a way you +had not anticipated, or that there is an existing function which performs the +same purpose, or that your function may be better off in its own eclass. If you +don't email gentoo-dev first, and end up breaking something, expect to be in a +lot of trouble. + +If there is an existing maintainer for an eclass (this is usually the case), you +**must** talk to the maintainer before committing any changes. + +It is not usually necessary to email the gentoo-dev list before making changes +to a non-general eclass which you maintain. Use common sense here. + +.. Warning:: Committing a broken eclass can kill huge numbers of packages. Since + ``repoman`` is not eclass-aware, be very sure you do proper testing. + +A simple way to verify syntax is ``bash -n foo.eclass``. + +Eclasses must **not** be removed from the tree, even if they are no longer used, +as this will cause problems for users who have installed packages which used the +eclass in question. + +Basic Eclass Format +------------------- + +An eclass is a ``bash`` script which is sourced within the ebuild environment. +Files should be a simple text file with a ``.eclass`` extension. Allowed +characters in the filename are lowercase letters, the digits 0-9, hyphens, +underscores and dots. Eclasses are not intrinsically versioned. + +Eclasses should start with the standard ebuild header, along with comments +explaining the maintainer and purpose of the eclass, and any other relevant +documentation. + +Eclass Variables +---------------- + +All eclasses must define two top level variables, ``ECLASS`` and ``INHERITED``. +The ``ECLASS`` variable must be set to the name of the eclass (without the +``.eclass`` suffix), and ``INHERITED`` must be set to ``"$INHERITED $ECLASS"``. + +Other top level variables may be defined as for ebuilds. If any USE flags are +used, ``IUSE`` must be set. The ``KEYWORDS`` variable must **not** be set in an +eclass. + +Eclass Functions +---------------- + +Eclasses may define functions. These functions will be visible to anything which +inherits the eclass. + +Simple Common Functions Eclass Example +-------------------------------------- + +As an example, the following eclass was written to illustrate a better way of +installing OSX application files during a discussion on this subject. It defines +a single function, ``domacosapp``. + +.. CODESAMPLE eclass-writing-1.ebuild + +Export Functions +---------------- + +An eclass may provide default implementations for any of the standard ebuild +functions (``src_unpack``, ``pkg_postinst`` etc). This can be done either as a +simple function definition (which is not multiple eclass friendly) or using +``EXPORT_FUNCTIONS``. Functions given to ``EXPORT_FUNCTIONS`` are implemented +as normal, but have their name prefixed with ``${ECLASS}_``. + +Important: Only 'standard' functions should be specified in +``EXPORT_FUNCTIONS``. + +.. Note:: ``EXPORT_FUNCTIONS`` is a function, *not* a variable. + +If multiple eclasses export the same function, the latest (inherited last) +defined version wins. If an ebuild defines a function that is exported, this +gets priority over any eclass version. This can be used to override +eclass-defined defaults -- for example, say we had ``fnord.eclass``: + +.. CODESAMPLE eclass-writing-2.ebuild + +Then an ebuild could do this: + +.. CODESAMPLE eclass-writing-3.ebuild + +Simple Build System Eclass Example +---------------------------------- + +A simple eclass which defines a number of functions and a default +``src_compile`` for the (hypothetical) ``jmake`` build system might look +something like the following: + +.. CODESAMPLE eclass-writing-4.ebuild + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/function-reference/build-functions/text.rst b/function-reference/build-functions/text.rst new file mode 100644 index 0000000..f6c68f9 --- /dev/null +++ b/function-reference/build-functions/text.rst @@ -0,0 +1,18 @@ +Build Functions Reference +========================= + +The following functions, which are all provided by ``ebuild.sh``, are useful +during the unpack and compile stages. + +====================== ====================================================== +Function Details +====================== ====================================================== +``unpack archives`` Unpack the specified archives. +``econf args`` Wrapper for ``./configure``. Passes on all ``args``. +``emake args`` Wrapper for ``make``. Passes on all ``args``. +``einstall args`` Wrapper for ``make install``, only to be used if ``make + DESTDIR="${D}"`` is unsuitable. +====================== ====================================================== + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/function-reference/install-functions/text.rst b/function-reference/install-functions/text.rst new file mode 100644 index 0000000..fedb788 --- /dev/null +++ b/function-reference/install-functions/text.rst @@ -0,0 +1,70 @@ +Install Functions Reference +=========================== + +The following functions, which are all provided ``ebuild.sh`` and the standard +library, handle various install-related tasks. ``${D}`` is automatically handled +for all of these functions. + +============== ====================================================== +Function Details +============== ====================================================== +``insinto`` Change install location for ``doins``, ``newins`` etc +``exeinto`` Change install location for ``doexe``, ``newexe`` etc +``docinto`` Change install location for ``dodoc``, ``newdoc`` etc +``insopts`` Specify arguments passed to ``install`` (eg ``-s``, ``-m644``). +``diropts`` Specify arguments passed to ``install`` for directories +``exeopts`` Specify arguments passed to ``install`` for executables +``libopts`` Specify arguments passed to ``install`` for libraries +``dobin`` Install a binary +``doconfd`` Install an ``/etc/conf.d`` file +``dodir`` Install a directory +``dodoc`` Install a documentation file +``doenvd`` Install an ``/etc/env.d`` file +``doexe`` Install an executable +``dohard`` Create a hardlink to the first argument from the second argument +``dohtml`` Install an HTML documentation file +``doinfo`` Install a GNU Info document +``doinitd`` Install an ``/etc/init.d`` file +``doins`` Install a miscellaneous file +``dojar`` Install a ``.jar`` file +``dolib`` Install a library file +``dolib.a`` Install a library (``.a``) file +``dolib.so`` Install a library (shared object) file +``doman`` Install a man page +``domo`` Install a Gettext ``.mo`` file +``dopython`` Install a Python file +``dosbin`` Install an ``sbin/`` file +``dosym`` Create a symlink from the second parameter to the first + parameter +``fowners`` Call ``chown`` with the first argument as the mode on all + additional arguments. +``fperms`` Call ``chown`` with the first argument as the user on all + additional arguments. +``keepdir`` Create a directory with an empty ``.keep`` file in it. +``newbin`` Install a binary using the second argument as the name. +``newconfd`` Install an ``/etc/conf.d`` entry using the second argument as the + name. +``newdoc`` Install a documentation file using the second argument as the + name. +``newenvd`` Install an ``/etc/env.d`` file using the second argument as the + name. +``newexe`` Install an executable file using the second argument as the name. +``newinitd`` Install an ``/etc/init.d`` file using the second argument as the + name. +``newins`` Install a miscellaneous file using the second argument as the + name. +``newlib.a`` Install a ``.a`` library file using the second argument as the + name. +``newlib.so`` Install a ``.so`` library file using the second argument as the + name. +``newman`` Install a manual page using the second argument as the name. +``newsbin`` Install an ``sbin`` file using the second argument as the name. +============== ====================================================== + +The ``do*`` functions, when given multiple arguments, will work upon multiple +targets. The ``new*`` functions take exactly two arguments (except as noted) -- +the first is the source name, the second the name to use when installing. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/function-reference/message-functions/text.rst b/function-reference/message-functions/text.rst new file mode 100644 index 0000000..8c56778 --- /dev/null +++ b/function-reference/message-functions/text.rst @@ -0,0 +1,34 @@ +Message Functions Reference +=========================== + +The following functions, which are provided by ``functions.sh``, can be used for +displaying informational messages. + +====================== ====================================================== +Function Details +====================== ====================================================== +``einfo`` Display an informational message. +``einfon`` Display an informational message with no trailing + newline. +``ewarn`` Display a warning message. +``eerror`` Display an error message. +``ebegin`` Display the message for the start of an action block. +``eend`` Display the end of an action block. +====================== ====================================================== + +The following are available from ``eutils.eclass``: + +====================== ====================================================== +Function Details +====================== ====================================================== +``epause`` Pause for the specified number (must be a positive + integer) of seconds. Defaults to a sane value. +``ebeep`` Beep the specified number (must be a positive integer) of + times. Defaults to a sane value. +====================== ====================================================== + +See `Messages`_ for a detailed discussion. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/function-reference/query-functions/text.rst b/function-reference/query-functions/text.rst new file mode 100644 index 0000000..d22cac5 --- /dev/null +++ b/function-reference/query-functions/text.rst @@ -0,0 +1,31 @@ +Query Functions Reference +========================= + +The following functions, which are provided by ``ebuild.sh``, can be used to +query variables and similar state. + +======================= ====================================================== +Function Details +======================= ====================================================== +``use flagname`` Returns a true value if and only if ``flagname`` is + included in ``USE`` +``useq flagname`` As ``use``, guaranteed to produce no output. +``usev flagname`` As ``use``, echoes ``flagname`` upon success. +``use_enable flag str`` Echoes either ``--enable-str`` or ``--disable-str`` + depending upon ``useq flag``. If ``str`` is not + specified, uses ``flag`` instead. +``use_with flag str`` As ``use_enable``, but ``--with-`` or ``without-``. +``has flag string`` Returns true if ``flag`` is included in the flag list + ``string`` (example: ``if has ccache $FEATURES ; then``). +``hasq flag string`` As ``has``, guaranteed quiet. +``hasv flag string`` As ``has``, echoes ``flag`` on success. +``portageq`` Wrapper for ``portageq`` +``best_version pkg`` Echoes the 'best' version of ``pkg`` which is currently + installed. +``has_version pkg`` True if ``pkg`` (can include version specifiers) is + installed. +======================= ====================================================== + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/function-reference/sandbox-functions/text.rst b/function-reference/sandbox-functions/text.rst new file mode 100644 index 0000000..7fea370 --- /dev/null +++ b/function-reference/sandbox-functions/text.rst @@ -0,0 +1,31 @@ +Sandbox Functions Reference +=========================== + +The following functions, which are all provided by ``ebuild.sh``, handle working +with the sandbox. + +====================== ====================================================== +Function Details +====================== ====================================================== +``addread`` Add one single additional item to the sandbox allowed + read list. +``addwrite`` Add one single additional item to the sandbox allowed + write list. **Note**: If at all possible, use + ``addpredict`` instead. Using ``addwrite`` is **not** an + appropriate alternative to making your package build + sandbox-friendly. +``adddeny`` Add one single additional item to the sandbox deny write + list. +``addpredict`` Add one single additional item to the sandbox predict + (pretend to allow write) list. +====================== ====================================================== + +None of these functions accept multiple arguments in one call. The sandbox is +recursive, so to allow predicted writes to ``/foo/bar`` and ``/foo/baz``, +``addpredict /foo`` would be sufficient. + +See `Sandbox`_ for details on how the sandbox works. See `Handling Access +Violations`_ for how to handle sandbox-related build problems. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/function-reference/text.rst b/function-reference/text.rst new file mode 100644 index 0000000..da0d663 --- /dev/null +++ b/function-reference/text.rst @@ -0,0 +1,9 @@ +Function Reference +================== + +The following functions are available for use in ebuilds: + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/autotools/aclocal-1.ebuild b/general-concepts/autotools/aclocal-1.ebuild new file mode 100644 index 0000000..c23a5a1 --- /dev/null +++ b/general-concepts/autotools/aclocal-1.ebuild @@ -0,0 +1,6 @@ +# vim: set ft=ebuild + +einfo "Regenerating autotools files..." +cp ${WORKDIR}/gentoo-m4 ${S}/m4 || die "m4 copy failed" +WANT_AUTOCONF="2.5" aclocal -I ${S}/m4 || die "aclocal failed" +WANT_AUTOCONF="2.5" autoconf || die "autoconf failed" diff --git a/general-concepts/autotools/aclocal-1.txt b/general-concepts/autotools/aclocal-1.txt new file mode 100644 index 0000000..c23a5a1 --- /dev/null +++ b/general-concepts/autotools/aclocal-1.txt @@ -0,0 +1,6 @@ +# vim: set ft=ebuild + +einfo "Regenerating autotools files..." +cp ${WORKDIR}/gentoo-m4 ${S}/m4 || die "m4 copy failed" +WANT_AUTOCONF="2.5" aclocal -I ${S}/m4 || die "aclocal failed" +WANT_AUTOCONF="2.5" autoconf || die "autoconf failed" diff --git a/general-concepts/autotools/aclocal-2.ebuild b/general-concepts/autotools/aclocal-2.ebuild new file mode 100644 index 0000000..4d9665e --- /dev/null +++ b/general-concepts/autotools/aclocal-2.ebuild @@ -0,0 +1,5 @@ +# vim: set ft=ebuild + +einfo "Regenerating autotools files..." +WANT_AUTOCONF="2.5" aclocal -I ${WORKDIR}/gentoo-m4 || die "aclocal failed" +WANT_AUTOCONF="2.5" autoconf || die "autoconf failed" diff --git a/general-concepts/autotools/aclocal-2.txt b/general-concepts/autotools/aclocal-2.txt new file mode 100644 index 0000000..4d9665e --- /dev/null +++ b/general-concepts/autotools/aclocal-2.txt @@ -0,0 +1,5 @@ +# vim: set ft=ebuild + +einfo "Regenerating autotools files..." +WANT_AUTOCONF="2.5" aclocal -I ${WORKDIR}/gentoo-m4 || die "aclocal failed" +WANT_AUTOCONF="2.5" autoconf || die "autoconf failed" diff --git a/general-concepts/autotools/autoconf-1.txt b/general-concepts/autotools/autoconf-1.txt new file mode 100644 index 0000000..9a57cca --- /dev/null +++ b/general-concepts/autotools/autoconf-1.txt @@ -0,0 +1,9 @@ +# vim: set ft=config : + +dnl Process this file with autoconf +AC_INIT(appname, 0.1) +AC_PREREQ(2.5) +AC_CONFIG_SRCDIR(src/main.c) +AC_CONFIG_AUX_DIR(config) +AM_INIT_AUTOMAKE(1.8) + diff --git a/general-concepts/autotools/autoconf-2.txt b/general-concepts/autotools/autoconf-2.txt new file mode 100644 index 0000000..5353c35 --- /dev/null +++ b/general-concepts/autotools/autoconf-2.txt @@ -0,0 +1,7 @@ +# vim: set ft=config : + +dnl Check for toolchain and install components +AC_PROG_CC +AC_PROG_INSTALL +AC_PROG_LN_S +AC_PROG_RANLIB diff --git a/general-concepts/autotools/autoconf-3.txt b/general-concepts/autotools/autoconf-3.txt new file mode 100644 index 0000000..3ccffd1 --- /dev/null +++ b/general-concepts/autotools/autoconf-3.txt @@ -0,0 +1,7 @@ +# vim: set ft=config : + +dnl Check for sed +AC_CHECK_PROGS(regex_cmd, sed) +if test x$regex_cmd = "x" ; then + AC_MSG_ERROR([sed is required to build the data files.]) +fi diff --git a/general-concepts/autotools/autoconf-4.txt b/general-concepts/autotools/autoconf-4.txt new file mode 100644 index 0000000..6eb94dd --- /dev/null +++ b/general-concepts/autotools/autoconf-4.txt @@ -0,0 +1,5 @@ +# vim: set ft=config : + +dnl Check that our compiler can do const and inline +AC_C_CONST +AC_C_INLINE diff --git a/general-concepts/autotools/autoconf-5.txt b/general-concepts/autotools/autoconf-5.txt new file mode 100644 index 0000000..351ee3b --- /dev/null +++ b/general-concepts/autotools/autoconf-5.txt @@ -0,0 +1,9 @@ +# vim: set ft=config : + +dnl Check for standard headers: +AC_HEADER_STDC +AC_HEADER_DIRENT +AC_CHECK_HEADERS([stdlib.h stdio.h libintl.h locale.h]) + +dnl Check for libraries: +AC_CHECK_LIB(ssl, SSL_free) diff --git a/general-concepts/autotools/autoconf-6.txt b/general-concepts/autotools/autoconf-6.txt new file mode 100644 index 0000000..e76a60a --- /dev/null +++ b/general-concepts/autotools/autoconf-6.txt @@ -0,0 +1,4 @@ +# vim: set ft=config : + +dnl Check for functions: +AC_CHECK_FUNCS([setlocale strtol]) diff --git a/general-concepts/autotools/autoconf-7.txt b/general-concepts/autotools/autoconf-7.txt new file mode 100644 index 0000000..7340248 --- /dev/null +++ b/general-concepts/autotools/autoconf-7.txt @@ -0,0 +1,4 @@ +# vim: set ft=config : + +AM_CONFIG_HEADER(config.h) +AC_OUTPUT(Makefile src/Makefile nls/Makefile man/Makefile tests/Makefile) diff --git a/general-concepts/autotools/autoconf-8.txt b/general-concepts/autotools/autoconf-8.txt new file mode 100644 index 0000000..1fa471c --- /dev/null +++ b/general-concepts/autotools/autoconf-8.txt @@ -0,0 +1,11 @@ +# vim: set ft=config : + +AC_MSG_CHECKING(--enable-cscope argument) +AC_ARG_ENABLE(cscope, + [ --enable-cscope Include cscope interface.], + [enable_cscope=$enableval], + [enable_cscope="no"]) +AC_MSG_RESULT($enable_cscope) +if test "$enable_cscope" = "yes"; then + AC_DEFINE(FEAT_CSCOPE) +fi diff --git a/general-concepts/autotools/autoconf-9.txt b/general-concepts/autotools/autoconf-9.txt new file mode 100644 index 0000000..e5864e1 --- /dev/null +++ b/general-concepts/autotools/autoconf-9.txt @@ -0,0 +1,8 @@ +# vim: set ft=config : + +AC_MSG_CHECKING([whether to enable foo]) +AC_ARG_WITH(foo, + [ --with-foo enable foo support], + with_foo=$withval, + with_foo=yes) +AC_MSG_RESULT($with_foo) diff --git a/general-concepts/autotools/automake-1.txt b/general-concepts/autotools/automake-1.txt new file mode 100644 index 0000000..da968fa --- /dev/null +++ b/general-concepts/autotools/automake-1.txt @@ -0,0 +1,4 @@ +# vim: set ft=automake : + +bin_PROGRAMS = myapp +myapp_SOURCES = myapp_commandline.c myapp.c diff --git a/general-concepts/autotools/automake-2.txt b/general-concepts/autotools/automake-2.txt new file mode 100644 index 0000000..d05bdb8 --- /dev/null +++ b/general-concepts/autotools/automake-2.txt @@ -0,0 +1,8 @@ +# vim: set ft=automake : + +CLEANFILES = glep31check.1 +man_MANS = glep31check.1 +EXTRA_DIST = glep31check.in + +%.1 : %.in + @regex_cmd@ -e "s,\@VERSION\@,$(VERSION),g" $? > $@ diff --git a/general-concepts/autotools/diagram.svg b/general-concepts/autotools/diagram.svg new file mode 100644 index 0000000..1f3eda8 --- /dev/null +++ b/general-concepts/autotools/diagram.svg @@ -0,0 +1,102 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg viewBox="0 50 510 360" xmlns="http://www.w3.org/2000/svg" version="1.1"> + <desc>Autotools Build Process</desc> + <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" /> + + <rect x="0" y="70" width="470" height="122" + stroke-width="1" stroke="black" fill="none" + stroke-dasharray="5,5" rx="10" ry="10" /> + <text style="text-anchor: middle; font-style: italic;" + x="400" y="150">Usually handled</text> + <text style="text-anchor: middle; font-style: italic;" + x="400" y="164">by upstream</text> + + <rect x="130" y="197" width="330" height="63" + stroke-width="1" stroke="black" fill="none" + stroke-dasharray="5,5" rx="10" ry="10" /> + <text style="text-anchor: middle; font-style: italic;" + x="410" y="225">Shipped with</text> + <text style="text-anchor: middle; font-style: italic;" + x="410" y="239">the package</text> + + <rect x="10" y="150" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="50" y="170">Makefile.am</text> + + <line x1="90" y1="165" x2="130" y2="165" stroke-width="2" stroke="black" /> + <line x1="130" y1="165" x2="122" y2="160" stroke-width="2" stroke="black" /> + <line x1="130" y1="165" x2="122" y2="170" stroke-width="2" stroke="black" /> + + <polygon points="130,165 180,145 230,165 180,185" fill="#ffffff" + stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="180" y="169">automake</text> + + <line x1="180" y1="185" x2="180" y2="215" stroke-width="2" stroke="black" /> + <line x1="185" y1="207" x2="180" y2="215" stroke-width="2" stroke="black" /> + <line x1="175" y1="207" x2="180" y2="215" stroke-width="2" stroke="black" /> + + <rect x="140" y="215" width="80" height="30" + fill="#ccffcc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="180" y="235">Makefile.in</text> + + <line x1="220" y1="230" x2="260" y2="230" stroke-width="2" stroke="black" /> + <line x1="260" y1="230" x2="252" y2="235" stroke-width="2" stroke="black" /> + <line x1="260" y1="230" x2="252" y2="225" stroke-width="2" stroke="black" /> + + <polygon points="260,230 310,210 360,230 310,250" fill="#ccffcc" + stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="310" y="234">configure</text> + + <line x1="310" y1="115" x2="310" y2="210" stroke-width="2" stroke="black" /> + <line x1="315" y1="202" x2="310" y2="210" stroke-width="2" stroke="black" /> + <line x1="305" y1="202" x2="310" y2="210" stroke-width="2" stroke="black" /> + + <polygon points="260,95 310,75 360,95 310,115" fill="#ffffff" + stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="310" y="99">autoconf</text> + + + <line x1="220" y1="95" x2="260" y2="95" stroke-width="2" stroke="black" /> + <line x1="260" y1="95" x2="252" y2="90" stroke-width="2" stroke="black" /> + <line x1="260" y1="95" x2="252" y2="100" stroke-width="2" stroke="black" /> + + + <rect x="140" y="80" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="180" y="93" >configure.in /</text> + <text style="text-anchor: middle;" x="180" y="105">configure.ac</text> + + <line x1="90" y1="165" x2="130" y2="165" stroke-width="2" stroke="black" /> + <line x1="130" y1="165" x2="122" y2="160" stroke-width="2" stroke="black" /> + <line x1="130" y1="165" x2="122" y2="170" stroke-width="2" stroke="black" /> + + <line x1="310" y1="250" x2="310" y2="285" stroke-width="2" stroke="black" /> + <line x1="315" y1="278" x2="310" y2="285" stroke-width="2" stroke="black" /> + <line x1="305" y1="278" x2="310" y2="285" stroke-width="2" stroke="black" /> + + <rect x="270" y="285" width="80" height="30" + fill="#ccffcc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="310" y="305">Makefile</text> + + <line x1="350" y1="300" x2="390" y2="300" stroke-width="2" stroke="black" /> + <line x1="390" y1="300" x2="382" y2="295" stroke-width="2" stroke="black" /> + <line x1="390" y1="300" x2="382" y2="305" stroke-width="2" stroke="black" /> + + <polygon points="390,300 440,280 490,300 440,320" fill="#ffffff" + stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="440" y="304">make</text> + + <line x1="440" y1="320" x2="440" y2="355" stroke-width="2" stroke="black" /> + <line x1="435" y1="348" x2="440" y2="355" stroke-width="2" stroke="black" /> + <line x1="445" y1="348" x2="440" y2="355" stroke-width="2" stroke="black" /> + + <ellipse cx="440" cy="375" rx="50" ry="20" stroke-width="2" stroke="black" + fill="#ffcccc" /> + <text style="text-anchor: middle;" x="440" y="378">program</text> + +</svg> + +<!-- vim: set ft=xml sw=4 sts=4 et : --> + diff --git a/general-concepts/autotools/patching-1.ebuild b/general-concepts/autotools/patching-1.ebuild new file mode 100644 index 0000000..5237c02 --- /dev/null +++ b/general-concepts/autotools/patching-1.ebuild @@ -0,0 +1,19 @@ +# + +src_unpack() { + unpack ${A} + cd "${S}" + + # Remove problematic LDFLAGS declaration + sed -i -e '/^LDFLAGS/d' src/Makefile.am + + # Rerun autotools + einfo "Regenerating autotools files..." + WANT_AUTOCONF=2.5 autoconf || die "autoconf failed" + WANT_AUTOMAKE=1.9 automake || die "automake failed" +} + +src_compile() { + econf $(use_enable nls) || die "econf failed" + emake || die "emake failed" +} diff --git a/general-concepts/autotools/quoting-1.txt b/general-concepts/autotools/quoting-1.txt new file mode 100644 index 0000000..db27eef --- /dev/null +++ b/general-concepts/autotools/quoting-1.txt @@ -0,0 +1,7 @@ +# vim: set ft=config : + +AC_MSG_RESULT(the first) +AC_MSG_RESULT([the second]) +AC_MSG_RESULT("the third") +AC_MSG_RESULT(@<:@the fourth@:>@) +AC_MSG_RESULT([@<:@the fifth@:>@]) diff --git a/general-concepts/autotools/text.rst b/general-concepts/autotools/text.rst new file mode 100644 index 0000000..17bc38c --- /dev/null +++ b/general-concepts/autotools/text.rst @@ -0,0 +1,355 @@ +The Basics of Autotools +======================= + +.. Todo:: This is too long for `General Concepts`_. It needs to be split up and + moved somewhere, either to a top-level of its own or into `Appendices`_. + +An understanding of GNU autotools (``automake``, ``autoconf`` etc) can be useful +when working with ebuilds: + +* Finding and correcting build issues is often easier if the build system is + not seen simply as a scary black box. +* The autotools input files can help when determining a package's build-time + dependencies. +* The risk of accidentally breaking something by patching the wrong file at the + wrong time is greatly reduced if the relationship between the build system + files is understood. + +Major Autotools Components +-------------------------- + +Autotools is a collection of related packages which, when used together, remove +much of the difficulty involved in creating portable software. These tools, +together with a few relatively simple upstream-supplied input files, are used to +create the build system for a package. + +.. figure:: diagram.png + :alt: How autotools fits together + + A basic overview of how the main autotools components fit together + +In a simple setup: + +* The ``autoconf`` program produces a ``configure`` script from either + ``configure.in`` or ``configure.ac`` (see note below). +* The ``automake`` program produces a ``Makefile.in`` from a ``Makefile.am``. +* The ``configure`` script is run to produce one or more ``Makefile`` files from + ``Makefile.in`` files. +* The ``make`` program uses the ``Makefile`` to compile the program. + + +.. Note:: The ``configure.in`` name used to be standard. However, the GNU + documentation now recommends ``configure.ac`` as it is more obvious which + program should be used when processing it. The files perform the same purpose + and have the same format -- the only difference is the name. + +You will see autotools being used variously in both ``src_unpack`` and +``src_compile``. The QA people prefer it in ``src_unpack`` -- the rationale is +that ``src_unpack`` handles "getting the package ready to be compiled" -- but +there is no official policy which mandates this. + +The ``autoreconf`` tool supposedly runs ``autoconf`` (and ``automake``, +``autoheader``, ``aclocal``, ``autopoint`` and ``libtoolize``) as necessary. +Sometimes it works. Some packages ship a shell script named ``autogen.sh`` which +does the same thing (this is *not* related to ``autogen``). + +.. Warning:: You must **not** attempt to modify any of the generated files in + between running ``configure`` and ``make``. This can lead to autotools + trying to be clever and recreate the files, in turn leading to your changes + being removed. In some situations this will also result in ``./configure`` + arguments being silently dropped, which can give broken dependencies. + The best way to proceed is usually to work with the ``.ac`` / ``.in`` files + instead. + +Simple Autotools Patching Example +--------------------------------- + +The following snippet illustrates the correct way to proceed after patching +either ``Makefile.am`` or ``configure.ac``: + +.. CODESAMPLE patching-1.ebuild + +The ``einfo`` message before running autotools is not mandatory. However, these +steps can sometimes take a while and may produce no output, so it may make sense +to let the user know that something is still happening. See `Messages`_. + +The ``configure.ac`` File +------------------------- + +The ``configure.ac`` file is used to create the ``./configure`` script. It +consists of a series of macros which are processed and expanded by ``autoconf``. +These macros can check for packages and libraries, handle ``--enable`` and +``--with`` switches, and generate various files. + +Basic Format of ``configure.ac`` +'''''''''''''''''''''''''''''''' + +The ``configure.ac`` file is a basic text file. Indenting and whitespace are +largely irrelevant. Comments are indicated by the string ``dnl`` (``dnl`` is +actually a macro which discards the remainder of the input -- it stands for +"discard new line"). + +If the previous sentence made you uneasy, you should probably stop reading this +page. It gets far worse. + +A typical file might start with something like the following: + +.. CODESAMPLE autoconf-1.txt + +The ``AC_PREREQ`` line, if present, tells you which ``autoconf`` version you +need. This is useful, because ``autoconf`` is not compatible between versions. +In the above example, we need ``=autoconf-2.5*``, and we should +``export WANT_AUTOCONF="2.5"`` (or use the ``autoconf-2.59`` script) when calling +``autoconf``. + +The ``AM_INIT_AUTOMAKE`` line tells us which ``automake`` version we need. +Again, there is little chance that an ``automake-1.7`` script will work properly +with ``automake-1.8``. Setting ``WANT_AUTOMAKE="1.8"`` in the environment can be +used to make an unversioned ``automake`` call run the correct version. + +.. Note:: The ``WANT_`` variables are a Gentoo feature that originally came from + Mandrake. Other distributions may handle things differently. + +Usually, some standard checks will follow: + +.. CODESAMPLE autoconf-2.txt + +For non-standard applications, you may also see manual checks: + +.. CODESAMPLE autoconf-3.txt + +You may also see checks for compiler features: + +.. CODESAMPLE autoconf-4.txt + +Library and header checks: + +.. CODESAMPLE autoconf-5.txt + +And function checks: + +.. CODESAMPLE autoconf-6.txt + +Often these will be all jumbled together without any useful comments. In some +cases, many of the checks done won't even be necessary for the application in +question -- most autotools code is copy/pasted rather than written from scratch, +and ``autoscan`` (a tool which helps write ``configure.ac``) is sometimes +over-eager to add in checks. + +The file will finish with some output functions: + +.. CODESAMPLE autoconf-7.txt + +These are used to make the ``./configure`` script generate the relevant files. + +Enable and Disable Checks +''''''''''''''''''''''''' + +So far we've only seen 'hard' dependencies. Many packages have *optional* +support for various extras (graphics toolkits, libraries which add +functionality, interpreters, features, ...). This is (if we're lucky) handled +via ``--enable-foo`` and ``--disable-foo`` switches to ``./configure``, which +are generated from ``autoconf`` rules. + +A simple ``--enable`` / ``--disable`` function might look something like the +following: + +.. CODESAMPLE autoconf-8.txt + +Sometimes more complicated checks are included based upon whether or not an +option is enabled. There are also some predefined macros which include +``AC_ARG_ENABLE``, so grepping ``configure.ac`` for ``AC_ARG_ENABLE`` may not +give a complete list. A better way is to use ``./configure --help`` and check +the output. + +.. Important:: The third argument is used when a ``--enable`` or ``--disable`` + switch to ``./configure`` is provided, and the fourth is used when such a + switch is *not* passed. A common misconception is that the third is enable + and the fourth is disable -- this is **not** the case. You may encounter + packages that get this wrong. + +A simple way to check that a package is using this macro properly is to +install the optional dependency, and then try all of ``./configure``, +``./configure --enable-foo`` and ``./configure --disable-foo``. If the second +and third runs give the same results, something is wrong. If the first run gives +a *different* result to the second and third, there is a good chance that a +misunderstanding of the ``AC_ARG_ENABLE`` arguments is to blame. + +With and Without Checks +''''''''''''''''''''''' + +A simple ``--with`` / ``--without`` check might look like: + +.. CODESAMPLE autoconf-9.txt + +Again, the third argument is for 'specified' and the fourth for 'not specified', +and there are standard macros which include ``with`` options. + +Automatic Checks +'''''''''''''''' + +It's possible to write autoconf rules which bypass the manual enable / disable +convention (or which just ignore what the user asks for). If your package does +this, it must be fixed to avoid dependency problems. + +The most common form is packages which simply use ``AC_CHECK_LIB`` to decide +whether or not to enable a feature. If you find a package which does this, you +**must** change the behaviour. + +Quoting Rules for ``configure.ac`` +'''''''''''''''''''''''''''''''''' + +Behind the scenes, ``autoconf`` makes heavy use of the ``m4`` macro processor to +do the work. The ``m4`` quote characters are set by ``autoconf`` to be ``[`` and +``]`` for opening and closing quotes respectively. Using ``"`` or ``'`` may +produce unexpected results. + +To include a literal left square bracket, the easiest thing to do is to use the +special string ``@<:@``. For a right bracket, use ``@:>@``. + +For example: + +.. CODESAMPLE quoting-1.txt + +gives: :: + + the first + the second + "the third" + [the fourth] + [the fifth] + +When in doubt, it is generally safest to quote macro arguments using ``[ ]`` +rather than leaving things unquoted. + +The ``Makefile.am`` Files +------------------------- + +The ``Makefile.am`` file is processed by ``automake`` to create ``Makefile.in``, +which is in turn processed by ``configure`` to create ``Makefile``, which is in +turn used by ``make`` to build the software. + +The basic format is like that of a ``Makefile``. However, you will see various +'special' variables being set, rather than every rule being written manually. + +A very simple example: + +.. CODESAMPLE automake-1.txt + +All the standard GNU rules will be generated, so ``make``, ``make clean``, +``make distclean``, ``make dist`` and so on will all work here. + +You may also see some standard ``Makefile`` constructs showing up whenever there +isn't a standard ``automake`` way of handling a certain task. For example: + +.. CODESAMPLE automake-2.txt + +Here, the ``@regex_cmd@`` variable will be substituted with whatever +``configure`` detects (``sed`` in this case) when creating the ``Makefile``. +This is handled via the macro ``AC_SUBST(VARNAME)`` in ``configure.ac``. + +Makefile Variables +'''''''''''''''''' + +Sometimes, badly behaved ``Makefile.am`` files will override user variables such +as ``CFLAGS``. This must not be allowed -- see `Not Filtering Variables`_. There +are separate special variables which should be used in these situations -- for +setting ``CFLAGS``, for example, a ``Makefile.am`` should use ``AM_CFLAGS`` so +that user preferences are not ignored. + +So, if a ``Makefile.am`` contains, say: :: + + CFLAGS="-Wall" + +You should ``sed`` or ``patch`` it to use: :: + + AM_CFLAGS="-Wall" + +Remember to manually run ``autoconf`` then ``automake`` if you do this. + +The ``config.h.in`` File +------------------------ + +The ``config.h.in`` file is generated by ``autoheader``. You shouldn't have to +worry about this usually, but occasionally you may need to run ``autoheader`` +manually as part of the build process if upstream do not ship a pre-generated +version. + +``aclocal`` and ``m4`` Files +---------------------------- + +In the ``configure.ac`` or ``configure.in`` files you can call not only the +default macros defined by ``autoconf`` and ``automake``, but also other +functions which can be defined by specific packages like libraries and programs +to check for their features in the correct manner. + +Those functions are (usually) defined in ``m4`` files placed in +the ``/usr/share/aclocal`` directory by packages. Problems can arise when you +need to regenerate the ``autotools`` files, because the functions used by the +``configure.ac`` file can be defined in an ``m4`` macro file which isn't +installed on the user's system. This is the case for example for some optional +features which require libraries and are disabled by ``USE`` flags. If the +``m4`` files aren't installed in the user's system, the ``autoconf`` step will +fail. + +To resolve this, most packages just ship the ``m4`` macro files needed for their +``configure.ac`` in an ``m4`` subdirectory in the source package. Unfortunately, +not all ``m4`` directories are complete, even if they are present. + +In those cases you need to find out the ``m4`` file, usually installed by the +dependency in ``/usr/share/aclocal``, and make sure that the ``src_unpack`` +stage both makes available those files to the autotools and calls ``aclocal`` to +recreate the ``aclocal.m4`` file which is used by ``autoconf`` when creating the +configure script. + +Usually it's more than one ``m4`` file which is missing, so you probably want to +package them in a tarball, and add it to ``SRC_URI``. After making sure that the +tarball is extracted somewhere in ``${WORKDIR}`` (say, in a ``gentoo-m4`` +directory), you usually have two general ways to handle those macro files, one +for packages which ships with an incomplete ``m4`` directory and one for +packages which ships without the ``m4`` directory. + +In the first case you usually want to do something like: + +.. CODESAMPLE aclocal-1.ebuild + +and so on. In the second case you can simplify it in this way: + +.. CODESAMPLE aclocal-2.ebuild + +without need to copy the files. + +It's always better inform upstream when the needed ``m4`` files are missing in +the distribution, asking them to add all the needed files in the source tarball +to avoid version conflicts if the macro changes. + +Libtool +------- + +.. Todo:: Stuff about libtool, libtoolize, elibtoolize, libtool.eclass. Which I + know almost nothing about... Yay! + +Further Autotools Reading +------------------------- + +For more details on autotools: + +* The book "GNU Autoconf, Automake and Libtool" by Gary V. Vaughan, Ben + Elliston, Tom Tromey and Ian Lance Taylor (often called "The Autobook") + provides a good but somewhat outdated description of autotools. It is + `freely available online <http://sources.redhat.com/autobook/>`_. + +* The GNU documentation for the various autotools components is of varying + quality and completeness: + + + `GNU automake Manual + <http://www.gnu.org/software/automake/manual/automake.html>`_ + + `GNU autoconf Manual <http://www.gnu.org/software/autoconf/manual/>`_ + + `GNU libtool Manual <http://www.gnu.org/software/libtool/manual.html>`_ + + `GNU m4 Manual <http://www.gnu.org/software/m4/manual/m4.html>`_ + +* There are some good overview lectures available online. `These slides + <http://vipe.technion.ac.il/~shlomif/lecture/Autotools/slides/>`_ are one + example. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/general-concepts/config-protect/text.rst b/general-concepts/config-protect/text.rst new file mode 100644 index 0000000..58736a8 --- /dev/null +++ b/general-concepts/config-protect/text.rst @@ -0,0 +1,20 @@ +Configuration File Protection +============================= + +Portage includes a system for configuration file protection which means ebuilds +don't have to worry about accidentally clobbering files in ``/etc``. This is +known as 'protection', and it is controlled by the ``CONFIG_PROTECT`` and +``CONFIG_PROTECT_MASK`` variables. + +Any directory which is listed in ``CONFIG_PROTECT`` (and any subdirectories +thereof), except for any which are listed in ``CONFIG_PROTECT_MASK`` (and +subdirectories) are automatically 'protected' by portage when copying an image +from ``DESTDIR`` to ``ROOT``. Rather than installing protected files directly, +portage will install them as ``._cfg0000_filename``. These can then be processed +by the ``etc-update`` or ``dispatch-conf`` files at the user's discretion. + +Packages must **not** attempt to override this system via ``pkg_postinst`` or +similar. If you need a file renamed, remove or changed in a particular way, you +should display a message informing the user. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/general-concepts/cvs-to-rsync/diagram.svg b/general-concepts/cvs-to-rsync/diagram.svg new file mode 100644 index 0000000..bc7e308 --- /dev/null +++ b/general-concepts/cvs-to-rsync/diagram.svg @@ -0,0 +1,142 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg viewBox="0 0 700 250" xmlns="http://www.w3.org/2000/svg" version="1.1"> + <desc>CVS to RSYNC Propagation</desc> + + <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" /> + + <rect x="10" y="110" width="80" height="30" + fill="#ffcccc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="50" y="130">Developers</text> + + <line x1="90" y1="125" x2="130" y2="125" stroke-width="2" stroke="black" /> + <line x1="130" y1="125" x2="122" y2="120" stroke-width="2" stroke="black" /> + <line x1="130" y1="125" x2="122" y2="130" stroke-width="2" stroke="black" /> + + + <rect x="10" y="60" width="80" height="30" + fill="#ffcccc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="50" y="80">Developers</text> + + <path d="M 90 75 Q 110 75 110 100 Q 110 130 130 125" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="10" y="160" width="80" height="30" + fill="#ffcccc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="50" y="180">Developers</text> + + <path d="M 90 175 Q 110 175 110 150 Q 110 120 130 125" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="130" y="110" width="80" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="170" y="130">CVS</text> + + <line x1="210" y1="125" x2="250" y2="125" stroke-width="2" stroke="black" /> + <line x1="250" y1="125" x2="242" y2="120" stroke-width="2" stroke="black" /> + <line x1="250" y1="125" x2="242" y2="130" stroke-width="2" stroke="black" /> + + + + <rect x="250" y="110" width="80" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="290" y="123">Staging</text> + <text style="text-anchor: middle;" x="290" y="135">Box</text> + + <line x1="330" y1="125" x2="370" y2="125" stroke-width="2" stroke="black" /> + <line x1="370" y1="125" x2="362" y2="120" stroke-width="2" stroke="black" /> + <line x1="370" y1="125" x2="362" y2="130" stroke-width="2" stroke="black" /> + + + + <rect x="370" y="110" width="80" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="410" y="130">rsync1</text> + + + + <line x1="490" y1="75" x2="482" y2="70" stroke-width="2" stroke="black" /> + <line x1="490" y1="75" x2="482" y2="80" stroke-width="2" stroke="black" /> + <path d="M 450 125 Q 470 125 470 100 Q 470 70 490 75" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="490" y="60" width="80" height="30" + fill="#ccffcc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="530" y="80">Public rsync</text> + + + + <line x1="450" y1="125" x2="490" y2="125" stroke-width="2" stroke="black" /> + <line x1="490" y1="125" x2="482" y2="120" stroke-width="2" stroke="black" /> + <line x1="490" y1="125" x2="482" y2="130" stroke-width="2" stroke="black" /> + + <rect x="490" y="110" width="80" height="30" + fill="#ccffcc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="530" y="130">Public rsync</text> + + + + <line x1="490" y1="175" x2="482" y2="170" stroke-width="2" stroke="black" /> + <line x1="490" y1="175" x2="482" y2="180" stroke-width="2" stroke="black" /> + <path d="M 450 125 Q 470 125 470 150 Q 470 180 490 175" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="490" y="160" width="80" height="30" + fill="#ccffcc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="530" y="180">Public rsync</text> + + + + <line x1="610" y1="25" x2="602" y2="20" stroke-width="2" stroke="black" /> + <line x1="610" y1="25" x2="602" y2="30" stroke-width="2" stroke="black" /> + <path d="M 570 75 Q 590 75 590 50 Q 590 20 610 25" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="610" y="10" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="30">Users</text> + + + + <line x1="570" y1="75" x2="610" y2="75" stroke-width="2" stroke="black" /> + <line x1="610" y1="75" x2="602" y2="70" stroke-width="2" stroke="black" /> + <line x1="610" y1="75" x2="602" y2="80" stroke-width="2" stroke="black" /> + + <rect x="610" y="60" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="80">Users</text> + + + + <line x1="570" y1="125" x2="610" y2="125" stroke-width="2" stroke="black" /> + <line x1="610" y1="125" x2="602" y2="120" stroke-width="2" stroke="black" /> + <line x1="610" y1="125" x2="602" y2="130" stroke-width="2" stroke="black" /> + + <rect x="610" y="110" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="130">Users</text> + + + <line x1="570" y1="175" x2="610" y2="175" stroke-width="2" stroke="black" /> + <line x1="610" y1="175" x2="602" y2="170" stroke-width="2" stroke="black" /> + <line x1="610" y1="175" x2="602" y2="180" stroke-width="2" stroke="black" /> + + <rect x="610" y="160" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="180">Users</text> + + + + <line x1="610" y1="225" x2="602" y2="220" stroke-width="2" stroke="black" /> + <line x1="610" y1="225" x2="602" y2="230" stroke-width="2" stroke="black" /> + <path d="M 570 175 Q 590 175 590 200 Q 590 230 610 225" + stroke-width="2" stroke="black" fill="none" /> + + <rect x="610" y="210" width="80" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="650" y="230">Users</text> + +</svg> + +<!-- vim: set ft=xml sw=4 sts=4 et : --> diff --git a/general-concepts/cvs-to-rsync/text.rst b/general-concepts/cvs-to-rsync/text.rst new file mode 100644 index 0000000..2af2148 --- /dev/null +++ b/general-concepts/cvs-to-rsync/text.rst @@ -0,0 +1,23 @@ +CVS to RSYNC +============ + +Changes made to the tree are propagated to the users in stages: + +* Developer commits to CVS. + +* Staging box syncs from CVS and generates the metadata cache. + +* ``rsync1`` syncs from the staging box. + +* Public rsync servers sync from ``rsync1``. + +* Users sync from the public rsync servers. + +.. figure:: diagram.png + :alt: CVS to RSYNC Propagation + + Diagram showing CVS to RSYNC Propagation + +The ``emerge-websync`` snapshot is made daily from the staging box. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/general-concepts/dependencies/basic-depend-sample.ebuild b/general-concepts/dependencies/basic-depend-sample.ebuild new file mode 100644 index 0000000..90f6d97 --- /dev/null +++ b/general-concepts/dependencies/basic-depend-sample.ebuild @@ -0,0 +1,5 @@ +# header + +DEPEND="dev-lang/ruby + dev-ruby/ruby-gtk2 + dev-ruby/mysql-ruby" diff --git a/general-concepts/dependencies/basic-depend-versions-sample.ebuild b/general-concepts/dependencies/basic-depend-versions-sample.ebuild new file mode 100644 index 0000000..1d64ebe --- /dev/null +++ b/general-concepts/dependencies/basic-depend-versions-sample.ebuild @@ -0,0 +1,3 @@ +# header + +DEPEND=">=dev-libs/openssl-0.9.7d" diff --git a/general-concepts/dependencies/block-sample.ebuild b/general-concepts/dependencies/block-sample.ebuild new file mode 100644 index 0000000..f8aaf00 --- /dev/null +++ b/general-concepts/dependencies/block-sample.ebuild @@ -0,0 +1,3 @@ +# header + +RDEPEND="!app-misc/foo" diff --git a/general-concepts/dependencies/block-version-sample.ebuild b/general-concepts/dependencies/block-version-sample.ebuild new file mode 100644 index 0000000..65e83d2 --- /dev/null +++ b/general-concepts/dependencies/block-version-sample.ebuild @@ -0,0 +1,3 @@ +# header + +RDEPEND="!<app-misc/foo-1.3" diff --git a/general-concepts/dependencies/ranged-depend-sample.ebuild b/general-concepts/dependencies/ranged-depend-sample.ebuild new file mode 100644 index 0000000..26955f7 --- /dev/null +++ b/general-concepts/dependencies/ranged-depend-sample.ebuild @@ -0,0 +1,4 @@ +# header + +DEPEND="gtk2? ( >=x11-libs/gtk+-2.4 ) + !gtk2? ( =x11-libs/gtk+-1.2* )" diff --git a/general-concepts/dependencies/text.rst b/general-concepts/dependencies/text.rst new file mode 100644 index 0000000..2ba10f2 --- /dev/null +++ b/general-concepts/dependencies/text.rst @@ -0,0 +1,197 @@ +Dependencies +============ + +Automatic dependency resolution is one of the most useful features provided by +``emerge``. + +Build Dependencies +------------------ + +The ``DEPEND`` ebuild variable should specify any dependencies which are +required to unpack, patch, compile or install the package (but see +`Implicit System Dependency`_ for exemptions). + +Runtime Dependencies +-------------------- + +The ``RDEPEND`` ebuild variable should specify any dependencies which are +required at runtime. This includes libraries (when dynamically linked), any data +packages and (for interpreted languages) the relevant interpreter. If this +variable is not specified, it defaults to the value of ``DEPEND``. + +Note that when installing from a binary package, only ``RDEPEND`` will be +checked. It is therefore necessary to include items even if they are also listed +in ``DEPEND``. + +Items which are in ``RDEPEND`` but not ``DEPEND`` could *in theory* be merged +*after* the target package. Portage does not currently do this. + +Post-Merge Dependencies +----------------------- + +The ``PDEPEND`` variable specifies dependencies which must be merged *after* the +package. This is sometimes used for plugins which have a dependency upon the +package being merged. Generally ``PDEPEND`` should be avoided in favour of +``RDEPEND`` except where this will create circular dependency chains. + +Implicit System Dependency +-------------------------- + +All packages have an implicit compile-time and runtime dependency upon the +entire ``system`` target. It is therefore not necessary, nor advisable, to +specify dependencies upon ``gcc``, ``libc`` and so on, except where specific +versions or packages (for example, ``glibc`` over ``uclibc``) are required. + +However, packages which are included in the ``system`` target, or are +dependencies of ``system`` target packages, should generally include a complete +dependency list (excluding bootstrap packages). This makes ``emerge -e system`` +possible when installing from a stage 1 or stage 2 tarball. + +Basic Dependency Syntax +----------------------- + +A basic ``*DEPEND`` specification might look like the following: + +.. CODESAMPLE basic-depend-sample.ebuild + +Each atom is the full category and name of a package. Atoms are separated by +arbitrary whitespace -- convention is to specify one atom per line for +readability purposes. When specifying names, the category part should be treated +as mandatory. + +Version Dependencies +-------------------- + +Sometimes a particular version of a package is needed. Where this is known, it +should be specified. A simple example: + +.. CODESAMPLE basic-depend-versions-sample.ebuild + +This states that at least version 0.9.7d of ``openssl`` is required. + +Version Specifiers +'''''''''''''''''' + +Available version specifiers are: + +========================= ==================================================== +Specifier Meaning +========================= ==================================================== +``>=app-misc/foo-1.23`` Version 1.23 or later is required. +``>app-misc/foo-1.23`` A version strictly later than 1.23 is required. +``~app-misc/foo-1.23`` Version 1.23 (or any ``1.23-r*``) is required. +``=app-misc/foo-1.23`` Exactly version 1.23 is required. If at all possible, + use the ``~`` form to simplify revision bumps. +``<=app-misc/foo-1.23`` Version 1.23 or older is required. +``<app-misc/foo-1.23`` A version strictly before 1.23 is required. +========================= ==================================================== + +Ranged Dependencies +''''''''''''''''''' + +To specify "version 2.x (not 1.x or 3.x)" of a package, it is necessary to use +the asterix postfix. This is most commonly seen in situations like: + +.. CODESAMPLE ranged-depend-sample.ebuild + +Note that the equals sign is mandatory, and that there is no dot before the +asterisk. + +Blockers +'''''''' + +Sometimes two packages cannot be installed in parallel. This is handled by +blockers. A blocker is specified as follows: + +.. CODESAMPLE block-sample.ebuild + +Note that blockers are usually *runtime* rather than buildtime. + +Specific versions can also be blocked: + +.. CODESAMPLE block-version-sample.ebuild + +Blockers can be optional based upon USE flags as per normal dependencies. + +SLOT Dependencies +----------------- + +It is not currently possible to depend upon a package in a particular ``SLOT``. +This is a shame. + +USE-Conditional Dependencies +---------------------------- + +To depend upon a certain package if and only if a given ``USE`` flag is set: + +.. CODESAMPLE use-depend-sample.ebuild + +It is also possible to depend upon a certain package if a given ``USE`` flag is +*not* set: + +.. CODESAMPLE use-depend-inv-sample.ebuild + +This should **not** be used for disabling a certain ``USE`` flag on a given +architecture. In order to do this, the architecture should add the ``USE`` +flag to their ``use.mask`` file in the ``profiles/default-linux/arch`` +directory of the Portage tree. + +This can be nested: + +.. CODESAMPLE use-depend-nest-sample.ebuild + +Virtual Dependencies +-------------------- + +To depend upon a virtual package, use ``virtual/whatever`` as the atom. + +Currently, you must not use any kind of version specification with virtuals -- +see `GLEP 37`_ for details and a proposed solution. + +Any of Many Dependencies +------------------------ + +To depend on either ``foo`` or ``bar``: + +.. CODESAMPLE use-depend-either-sample.ebuild + +To depend on either ``foo`` or ``bar`` if the ``baz`` ``USE`` flag is set: + +.. CODESAMPLE use-depend-either-use-sample.ebuild + +Any of Many Versus USE +'''''''''''''''''''''' + +Say ``fnord`` can be built against either ``foo`` or ``bar``. Then a USE flag is +not necessary if and only if all of the following hold: + +* ``fnord`` is merged on a system which has ``foo`` and not ``bar`` installed. + ``foo`` is then unmerged, and ``bar`` is installed. ``fnord`` must continue to + work correctly. + +* A binary package of ``fnord`` made on a system with ``foo`` and not ``bar`` + can be taken and installed on a system with ``bar`` and not ``foo``. + +Built with USE Dependencies +--------------------------- + +Currently it is impossible to depend upon "``foo`` built with the ``bar`` +``USE`` flag enabled". This is a nuisance. + +Legacy Inverse USE-Conditional Dependency Syntax +------------------------------------------------ + +When looking through old ebuild versions or the occasional user-submitted +ebuild, you may see a ``*DEPEND`` atom in the form: + +.. CODESAMPLE use-depend-legacy-sample.ebuild + +**This syntax is no longer permitted**. It is exactly equivalent to the +following, which should be used instead: + +.. CODESAMPLE use-depend-nonlegacy-sample.ebuild + +It is useful to recognise the legacy syntax and to know that it is no longer +valid. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/general-concepts/dependencies/use-depend-either-sample.ebuild b/general-concepts/dependencies/use-depend-either-sample.ebuild new file mode 100644 index 0000000..c575405 --- /dev/null +++ b/general-concepts/dependencies/use-depend-either-sample.ebuild @@ -0,0 +1,3 @@ +# header + +DEPEND="|| ( app-misc/foo app-misc/bar )" diff --git a/general-concepts/dependencies/use-depend-either-use-sample.ebuild b/general-concepts/dependencies/use-depend-either-use-sample.ebuild new file mode 100644 index 0000000..464759e --- /dev/null +++ b/general-concepts/dependencies/use-depend-either-use-sample.ebuild @@ -0,0 +1,3 @@ +# HEADER + +DEPEND="baz? ( || ( app-misc/foo app-misc/bar ) )" diff --git a/general-concepts/dependencies/use-depend-inv-sample.ebuild b/general-concepts/dependencies/use-depend-inv-sample.ebuild new file mode 100644 index 0000000..6c1965b --- /dev/null +++ b/general-concepts/dependencies/use-depend-inv-sample.ebuild @@ -0,0 +1,3 @@ +# header + +RDEPEND="!crypt? ( net-misc/netkit-rsh )" diff --git a/general-concepts/dependencies/use-depend-legacy-sample.ebuild b/general-concepts/dependencies/use-depend-legacy-sample.ebuild new file mode 100644 index 0000000..45d7d51 --- /dev/null +++ b/general-concepts/dependencies/use-depend-legacy-sample.ebuild @@ -0,0 +1,3 @@ +# header + +DEPEND="use-flag? ( app-misc/foo ) : ( app-misc/bar )" diff --git a/general-concepts/dependencies/use-depend-nest-sample.ebuild b/general-concepts/dependencies/use-depend-nest-sample.ebuild new file mode 100644 index 0000000..6826689 --- /dev/null +++ b/general-concepts/dependencies/use-depend-nest-sample.ebuild @@ -0,0 +1,6 @@ +# header + +DEPEND="gtk? ( + gtk2? ( >=x11-libs/gtk+-2.4 ) + !gtk2? ( =x11-libs/gtk+-1.2* ) ) + !gtk? ( sys-libs/ncurses )" diff --git a/general-concepts/dependencies/use-depend-nonlegacy-sample.ebuild b/general-concepts/dependencies/use-depend-nonlegacy-sample.ebuild new file mode 100644 index 0000000..72087e7 --- /dev/null +++ b/general-concepts/dependencies/use-depend-nonlegacy-sample.ebuild @@ -0,0 +1,4 @@ +# header + +DEPEND="use-flag? ( app-misc/foo ) + !use-flag? ( app-misc/bar )" diff --git a/general-concepts/dependencies/use-depend-sample.ebuild b/general-concepts/dependencies/use-depend-sample.ebuild new file mode 100644 index 0000000..a0e3d73 --- /dev/null +++ b/general-concepts/dependencies/use-depend-sample.ebuild @@ -0,0 +1,5 @@ +# header + +DEPEND="perl? ( dev-lang/perl ) + ruby? ( >=dev-lang/ruby-1.8 ) + python? ( dev-lang/python )" diff --git a/general-concepts/digest-and-manifest/text.rst b/general-concepts/digest-and-manifest/text.rst new file mode 100644 index 0000000..613a9d0 --- /dev/null +++ b/general-concepts/digest-and-manifest/text.rst @@ -0,0 +1,24 @@ +Digest and Manifest +=================== + +In the tree, every package has a ``Manifest`` file. This file lives in the same +directory as the ebuilds for the package. The ``Manifest`` file contains digests +(currently MD5) and file size data for every file in the directory and any +subdirectories. This is used to verify integrity. + +The ``Manifest`` may be digitally signed. + +Inside the ``files/`` subdirectory, there is exactly one ``digest`` file per +ebuild. Each file contains a digest (currently MD5) and a file size for every +file listed in ``SRC_URI`` for the ebuild. This is used to verify downloads and +to catch any changed source files. + +When generating digests, it is necessary to include *all* of the files which +*could* be downloaded (``SRC_URI`` can contain conditional entries). Portage +will do this automatically if ``cvs`` is included in ``FEATURES``. + +To generate digests and ``Manifest``, use ``ebuild foo.ebuild digest``. When +committing, the ``Manifest`` file must be regenerated to handle any CVS keyword +expansion changes -- ``repoman`` will do this automatically. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/general-concepts/distributed-building/text.rst b/general-concepts/distributed-building/text.rst new file mode 100644 index 0000000..367ecb0 --- /dev/null +++ b/general-concepts/distributed-building/text.rst @@ -0,0 +1,6 @@ +Distributed and Parallel Building +================================= + +.. Todo:: write this + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/general-concepts/ebuild-revisions/text.rst b/general-concepts/ebuild-revisions/text.rst new file mode 100644 index 0000000..dc8dd9c --- /dev/null +++ b/general-concepts/ebuild-revisions/text.rst @@ -0,0 +1,23 @@ +Ebuild Revisions +================ + +Ebuilds may have a Gentoo revision number associated with them. This is a +``-rX`` suffix, where ``X`` is an integer -- see `File Naming Rules`_. This +component must only be used for Gentoo changes, not upstream releases. By +default, ``-r0`` is implied and should not be specified manually. + +Ebuilds should have their ``-rX`` incremented whenever a change is made which +will make a substantial difference to what gets installed by the package -- by +substantial, we generally mean "something for which many users would want to +upgrade". This is usually for bugfixes. + +Simple compile fixes do **not** warrant a revision bump; this is because they do +not affect the installed package for users who already managed to compile it. +Small documentation fixes are also usually not grounds for a new revision. + +When doing a revision bump, the usual rules about dropping to ``~arch`` apply. +See `Keywording on Upgrades`_. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/general-concepts/emerge-and-ebuild/diagram.svg b/general-concepts/emerge-and-ebuild/diagram.svg new file mode 100644 index 0000000..62bc8fd --- /dev/null +++ b/general-concepts/emerge-and-ebuild/diagram.svg @@ -0,0 +1,55 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg viewBox="0 100 500 220" xmlns="http://www.w3.org/2000/svg" version="1.1"> + <desc>Emerge and Ebuild</desc> + <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" /> + + <rect x="50" y="150" width="100" height="30" + fill="#ccffcc" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="100" y="170"># emerge foo</text> + + <line x1="150" y1="165" x2="200" y2="165" stroke-width="2" stroke="black" /> + <line x1="200" y1="165" x2="193" y2="160" stroke-width="2" stroke="black" /> + <line x1="200" y1="165" x2="193" y2="170" stroke-width="2" stroke="black" /> + + <rect x="200" y="150" width="100" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="250" y="170">emerge</text> + + <line x1="220" y1="180" x2="220" y2="250" stroke-width="2" stroke="black" /> + <line x1="220" y1="250" x2="215" y2="243" stroke-width="2" stroke="black" /> + <line x1="220" y1="250" x2="225" y2="243" stroke-width="2" stroke="black" /> + <text style="text-anchor: right;" x="210" y="220">$PN, phases</text> + + <line x1="280" y1="180" x2="280" y2="250" stroke-width="2" stroke="black" /> + <line x1="280" y1="180" x2="275" y2="187" stroke-width="2" stroke="black" /> + <line x1="280" y1="180" x2="285" y2="187" stroke-width="2" stroke="black" /> + <text style="text-anchor: left;" x="290" y="220">Image in $D</text> + + <rect x="200" y="250" width="100" height="30" + fill="#ffffff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="250" y="270">ebuild.sh</text> + + <rect x="50" y="250" width="100" height="30" + fill="#ccccff" stroke="black" stroke-width="2" /> + <text style="text-anchor: middle;" x="100" y="270">foo-1.23.ebuild</text> + + <line x1="150" y1="265" x2="200" y2="265" stroke-width="2" stroke="black" /> + <line x1="200" y1="265" x2="193" y2="260" stroke-width="2" stroke="black" /> + <line x1="200" y1="265" x2="193" y2="270" stroke-width="2" stroke="black" /> + + <line x1="300" y1="165" x2="350" y2="165" stroke-width="2" stroke="black" /> + <line x1="350" y1="165" x2="343" y2="160" stroke-width="2" stroke="black" /> + <line x1="350" y1="165" x2="343" y2="170" stroke-width="2" stroke="black" /> + + <ellipse cx="400" cy="165" rx="50" ry="20" stroke-width="2" stroke="black" + fill="#ffcccc" /> + <text style="text-anchor: middle;" x="400" y="164">Installed image</text> + <text style="text-anchor: middle;" x="400" y="177">in $ROOT</text> + +</svg> + +<!-- vim: set ft=xml sw=4 sts=4 et : --> + + diff --git a/general-concepts/emerge-and-ebuild/text.rst b/general-concepts/emerge-and-ebuild/text.rst new file mode 100644 index 0000000..f8d7615 --- /dev/null +++ b/general-concepts/emerge-and-ebuild/text.rst @@ -0,0 +1,16 @@ +Emerge and Ebuild Relationships +=============================== + +.. figure:: diagram.png + :alt: How emerge, ebuild and foo.ebuild interact + +The ``emerge`` program is a high level wrapper for ``ebuild.sh`` that handles +dependency tracking, safe installs and uninstalls and so on. ``emerge`` calls +``ebuild.sh`` during the build process, which in turn handles the ebuild file +and any eclasses. The ``${D}`` to ``${ROOT}`` install is handled by ``emerge``. + +.. Todo:: http://dev.gentoo.org/~g2boojum/portage.html + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/general-concepts/features/text.rst b/general-concepts/features/text.rst new file mode 100644 index 0000000..7f4fd6d --- /dev/null +++ b/general-concepts/features/text.rst @@ -0,0 +1,40 @@ +FEATURES +======== + +The ``FEATURES`` variable specifies options which affect how portage operates +and how packages are compiled. It is **not** used for settings which have a +substantial effect upon the resulting generated package. + +Relevant ``FEATURES`` for developers include: + +``autoaddcvs`` + Automatically runs a ``cvs add`` for certain files. + +``collision-protect`` + Raise an error if an installing package attempts to overwrite a file which + is provided by a different package. + +``cvs`` + Generate proper digests even when ``SRC_URI`` has conditional elements. + +``sandbox`` + Enable the sandbox. + +``sign`` + GPG sign manifest files. + +``strict`` + Do some extra checks for potentially dangerous situations (eg missing + ``Manifest`` files). + +``test`` + Enable the ``src_test`` phase. + +``userpriv`` + Drop to non-root privileges for certain phases. + +``usersandbox`` + Enables the sandbox even when running non-privileged. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/filesystem/text.rst b/general-concepts/filesystem/text.rst new file mode 100644 index 0000000..6abe677 --- /dev/null +++ b/general-concepts/filesystem/text.rst @@ -0,0 +1,55 @@ +Filesystem +========== + +The basic filesystem layout and purpose is as follows: + +* ``/bin``: Boot-critical applications +* ``/etc``: System administrator controlled configuration files +* ``/lib``: Boot-critical libraries +* ``/opt``: Binary-only applications. +* ``/sbin``: System administrator boot-critical applications +* ``/tmp``: Temporary data +* ``/usr``: General applications + + + ``/usr/bin``: Applications + + ``/usr/lib``: Libraries + + ``/usr/local``: Non-portage applications. **Ebuilds must not install here**. + + ``/usr/sbin``: Non-system-critical system administrator applications + + ``/usr/share``: Architecture independent application data and documentation + +* ``/var``: Program generated data + + + ``/var/cache``: Long term data which can be regenerated + + ``/var/lib``: General application generated data + + ``/var/log``: Log files + +Where possible, we prefer to put non-boot-critical applications in ``/usr`` +rather than ``/``. If a program is not needed in the boot process until after +filesystems are mounted then it generally does not belong on ``/``. + +Any binary which links against a library under ``/usr`` must itself go into +``/usr`` (or possibly ``/opt``). + +The ``/opt`` top-level should only be used for binary-only applications. +Binary-only applications must not be installed outside of ``/opt``. + +The ``/usr/local`` heirarchy is for non-portage software. Ebuilds must not +attempt to put anything in here. + +The ``/usr/share`` directory is for *architecture independent* application data +which is not modified at runtime. + +Try to avoid installing unnecessary things into ``/etc`` -- every file in there +is additional work for the system administrator. In particular, non-text files +and files that are not intended for system administrator usage should be moved +to ``/usr/share``. + +FHS +--- + +Gentoo does not consider the `Filesystem Hierarchy Standard +<http://www.pathname.com/fhs/>`__ to be an authoritative standard, although much +of our policy coincides with it. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/herds-and-projects/text.rst b/general-concepts/herds-and-projects/text.rst new file mode 100644 index 0000000..f05f850 --- /dev/null +++ b/general-concepts/herds-and-projects/text.rst @@ -0,0 +1,20 @@ +Herds and Projects +================== + +A *herd* is a collection of developers who maintain a collection of related +packages. A herd has an associated email address which can be used for bugzilla +assignments. This email address is **not** always ``herdname@gentoo.org`` -- for +example, because of the way Gentoo's email aliases are set up, the ``cron`` herd +use ``cron-bugs@gentoo.org`` (aliases cannot match system usernames). + +A *project* is a group formed for handling a particular general area. A project +may have herds associated with it. + +Sometimes herd and project names overlap -- for example, the ``sparc`` project +has an associated ``sparc`` herd which maintains sparc-specific packages (such +as the ``silo`` bootloader). This is *not* always the case. + +The ``herdstat`` tool can display useful information about herds. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/install-destinations/text.rst b/general-concepts/install-destinations/text.rst new file mode 100644 index 0000000..5fd0413 --- /dev/null +++ b/general-concepts/install-destinations/text.rst @@ -0,0 +1,20 @@ +Install Destinations +==================== + +When an ebuild runs the ``src_install`` phase, it installs an image of the +package in question from ``${S}`` into ``${D}``. Ebuilds must *not* attempt to +perform any operation upon the live filesystem at this stage -- this will break +binaries, and will (often) cause a sandbox violation notice. + +When installing, portage will install the image in ``${D}`` into ``${ROOT}``. By +default, ``${ROOT}`` points to ``/``, although the user can alter this -- for +example, the user may be building a minimal image for another system in a +different location. If your package must operate on the live filesystem (for +example, to create some cache files during ``pkg_postinst``), you must ensure +that you prefix any paths with ``${ROOT}``. + +When inside ``pkg_preinst``, the image to be installed can be accessed under +``"${IMAGE}"``. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/licenses/text.rst b/general-concepts/licenses/text.rst new file mode 100644 index 0000000..243a538 --- /dev/null +++ b/general-concepts/licenses/text.rst @@ -0,0 +1,20 @@ +Licenses +======== + +All ebuilds must specify a ``LICENSE`` (note the American English spelling) +variable. The value of this variable must be the name of a file in the portage +tree's ``licenses/`` directory. + +Adding New Licenses +------------------- + +If your package's license is not already in the tree, you must add the license +before committing the package. When adding the license, use a plain text file if +at all possible. Some licenses are PDF files rather than plain text -- this +should only be done if we are legally required to do so. + +It is not normally necessary to mail the ``gentoo-dev`` list before adding a new +license. You should only do so if the license could be considered 'questionable' +or if you are unsure as to the meaning of any part of it. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/general-concepts/linguas/text.rst b/general-concepts/linguas/text.rst new file mode 100644 index 0000000..13f6ca5 --- /dev/null +++ b/general-concepts/linguas/text.rst @@ -0,0 +1,11 @@ +Linguas +======= + +.. Todo:: Write this. From vapier: "used to specify languages users wish to have + support for. USE=nls covers generally natural language support, but LINGUAS + covers specific languages (see the games-rpg/nwn for example). the variable + is expanded for USE access in ebuilds. LINGUAS=de would automatically add + 'linguas_de' to USE." We also need strip-linguas examples. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/mirrors/diagram.svg b/general-concepts/mirrors/diagram.svg new file mode 100644 index 0000000..0af1f1c --- /dev/null +++ b/general-concepts/mirrors/diagram.svg @@ -0,0 +1,521 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + sodipodi:docbase="/home/plasmaroo" + sodipodi:docname="diagram.svg" + inkscape:version="0.41" + sodipodi:version="0.32" + version="1.0" + x="0.0000000" + y="0.0000000" + width="700.00000px" + height="250.00000px" + viewBox="0 0 700 250" + id="svg1546"> + <metadata + id="metadata71"> + <rdf:RDF + id="RDF73"> + <cc:Work + id="Work75" + rdf:about=""> + <dc:format + id="format77">image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" + id="type79" /> + </cc:Work> + </rdf:RDF> + </metadata> + <sodipodi:namedview + inkscape:current-layer="svg1546" + inkscape:window-y="264" + inkscape:window-x="164" + inkscape:cy="81.156529" + inkscape:cx="343.48587" + inkscape:zoom="0.97294509" + inkscape:window-height="541" + inkscape:window-width="968" + inkscape:pageshadow="2" + inkscape:pageopacity="1.0000000" + borderopacity="1.0" + bordercolor="#666666" + pagecolor="#eeeeee" + id="base" /> + <defs + id="defs1680" /> + <desc + id="desc1548">CVS to RSYNC Propagation</desc> + <rect + y="0.24284256" + x="-2.0556145" + height="260.03522" + width="710.21484" + id="rect1360" + style="fill:#eeeeee;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:1.0000000px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="10.000000" + y="110.00000" + style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000" + id="rect1551" /> + <text + x="50" + y="130" + style="text-anchor:middle" + id="text1553">Developers</text> + <line + id="line1555" + stroke="black" + stroke-width="2" + y2="125.00000" + x2="130.00000" + y1="125.00000" + x1="90.000000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1557" + stroke="black" + stroke-width="2" + y2="120.00000" + x2="122.00000" + y1="125.00000" + x1="130.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1559" + stroke="black" + stroke-width="2" + y2="130.00000" + x2="122.00000" + y1="125.00000" + x1="130.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="10.000000" + y="60.000000" + style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000" + id="rect1561" /> + <text + x="50" + y="80" + style="text-anchor:middle" + id="text1563">Developers</text> + <path + d="M 90.000000,75.000000 C 103.33333,75.000000 110.00000,83.333333 110.00000,100.00000 C 110.00000,120.00000 116.66667,128.33333 130.00000,125.00000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1565" /> + <rect + width="80.000000" + height="30.000000" + x="10.000000" + y="160.00000" + style="fill:#ffcccc;stroke:#000000;stroke-width:2.0000000" + id="rect1567" /> + <text + x="50" + y="180" + style="text-anchor:middle" + id="text1569">Developers</text> + <path + d="M 90.000000,175.00000 C 103.33333,175.00000 110.00000,166.66667 110.00000,150.00000 C 110.00000,130.00000 116.66667,121.66667 130.00000,125.00000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1571" /> + <rect + width="80.000000" + height="30.000000" + x="130.00000" + y="110.00000" + style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000" + id="rect1573" /> + <text + x="170" + y="130" + style="text-anchor:middle" + id="text1575">dev.gentoo</text> + <line + id="line1577" + stroke="black" + stroke-width="2" + y2="125.00000" + x2="250.00000" + y1="125.00000" + x1="210.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1579" + stroke="black" + stroke-width="2" + y2="120.00000" + x2="242.00000" + y1="125.00000" + x1="250.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1581" + stroke="black" + stroke-width="2" + y2="130.00000" + x2="242.00000" + y1="125.00000" + x1="250.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="250.00000" + y="110.00000" + style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000" + id="rect1583" /> + <text + x="290" + y="123" + style="text-anchor:middle" + id="text1585">Staging</text> + <text + x="290" + y="135" + style="text-anchor:middle" + id="text1587">Box</text> + <line + id="line1589" + stroke="black" + stroke-width="2" + y2="125.00000" + x2="370.00000" + y1="125.00000" + x1="330.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1591" + stroke="black" + stroke-width="2" + y2="120.00000" + x2="362.00000" + y1="125.00000" + x1="370.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1593" + stroke="black" + stroke-width="2" + y2="130.00000" + x2="362.00000" + y1="125.00000" + x1="370.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="370.00000" + y="110.00000" + style="fill:#ffffff;stroke:#000000;stroke-width:2.0000000" + id="rect1595" /> + <text + x="410" + y="130" + style="text-anchor:middle" + id="text1597">OSU Mirrors</text> + <line + id="line1599" + stroke="black" + stroke-width="2" + y2="70.000000" + x2="482.00000" + y1="75.000000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1601" + stroke="black" + stroke-width="2" + y2="80.000000" + x2="482.00000" + y1="75.000000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <path + d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,116.66667 470.00000,100.00000 C 470.00000,80.000000 476.66667,71.666667 490.00000,75.000000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1603" /> + <rect + width="80.000000" + height="30.000000" + x="490.00000" + y="60.000000" + style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000" + id="rect1605" /> + <text + x="530" + y="80" + style="text-anchor:middle" + id="text1607">Public mirror</text> + <line + id="line1609" + stroke="black" + stroke-width="2" + y2="125.00000" + x2="490.00000" + y1="125.00000" + x1="450.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1611" + stroke="black" + stroke-width="2" + y2="120.00000" + x2="482.00000" + y1="125.00000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1613" + stroke="black" + stroke-width="2" + y2="130.00000" + x2="482.00000" + y1="125.00000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="490.00000" + y="110.00000" + style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000" + id="rect1615" /> + <text + x="530" + y="130" + style="text-anchor:middle" + id="text1617">Public mirror</text> + <line + id="line1619" + stroke="black" + stroke-width="2" + y2="170.00000" + x2="482.00000" + y1="175.00000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1621" + stroke="black" + stroke-width="2" + y2="180.00000" + x2="482.00000" + y1="175.00000" + x1="490.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <path + d="M 450.00000,125.00000 C 463.33333,125.00000 470.00000,133.33333 470.00000,150.00000 C 470.00000,170.00000 476.66667,178.33333 490.00000,175.00000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1623" /> + <rect + width="80.000000" + height="30.000000" + x="490.00000" + y="160.00000" + style="fill:#ccffcc;stroke:#000000;stroke-width:2.0000000" + id="rect1625" /> + <text + x="530" + y="180" + style="text-anchor:middle" + id="text1627">Public mirror</text> + <line + id="line1629" + stroke="black" + stroke-width="2" + y2="20.000000" + x2="602.00000" + y1="25.000000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1631" + stroke="black" + stroke-width="2" + y2="30.000000" + x2="602.00000" + y1="25.000000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <path + d="M 570.00000,75.000000 C 583.33333,75.000000 590.00000,66.666667 590.00000,50.000000 C 590.00000,30.000000 596.66667,21.666667 610.00000,25.000000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1633" /> + <rect + width="80.000000" + height="30.000000" + x="610.00000" + y="10.000000" + style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" + id="rect1635" /> + <text + x="650" + y="30" + style="text-anchor:middle" + id="text1637">Users</text> + <line + id="line1639" + stroke="black" + stroke-width="2" + y2="75.000000" + x2="610.00000" + y1="75.000000" + x1="570.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1641" + stroke="black" + stroke-width="2" + y2="70.000000" + x2="602.00000" + y1="75.000000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1643" + stroke="black" + stroke-width="2" + y2="80.000000" + x2="602.00000" + y1="75.000000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="610.00000" + y="60.000000" + style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" + id="rect1645" /> + <text + x="650" + y="80" + style="text-anchor:middle" + id="text1647">Users</text> + <line + id="line1649" + stroke="black" + stroke-width="2" + y2="125.00000" + x2="610.00000" + y1="125.00000" + x1="570.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1651" + stroke="black" + stroke-width="2" + y2="120.00000" + x2="602.00000" + y1="125.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1653" + stroke="black" + stroke-width="2" + y2="130.00000" + x2="602.00000" + y1="125.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="610.00000" + y="110.00000" + style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" + id="rect1655" /> + <text + x="650" + y="130" + style="text-anchor:middle" + id="text1657">Users</text> + <line + id="line1659" + stroke="black" + stroke-width="2" + y2="175.00000" + x2="610.00000" + y1="175.00000" + x1="570.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1661" + stroke="black" + stroke-width="2" + y2="170.00000" + x2="602.00000" + y1="175.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1663" + stroke="black" + stroke-width="2" + y2="180.00000" + x2="602.00000" + y1="175.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <rect + width="80.000000" + height="30.000000" + x="610.00000" + y="160.00000" + style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" + id="rect1665" /> + <text + x="650" + y="180" + style="text-anchor:middle" + id="text1667">Users</text> + <line + id="line1669" + stroke="black" + stroke-width="2" + y2="220.00000" + x2="602.00000" + y1="225.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <line + id="line1671" + stroke="black" + stroke-width="2" + y2="230.00000" + x2="602.00000" + y1="225.00000" + x1="610.00000" + style="stroke:#000000;stroke-width:2.0000000" /> + <path + d="M 570.00000,175.00000 C 583.33333,175.00000 590.00000,183.33333 590.00000,200.00000 C 590.00000,220.00000 596.66667,228.33333 610.00000,225.00000" + style="fill:none;stroke:#000000;stroke-width:2.0000000" + id="path1673" /> + <rect + width="80.000000" + height="30.000000" + x="610.00000" + y="210.00000" + style="fill:#ccccff;stroke:#000000;stroke-width:2.0000000" + id="rect1675" /> + <text + x="650" + y="230" + style="text-anchor:middle" + id="text1677">Users</text> +</svg> diff --git a/general-concepts/mirrors/text.rst b/general-concepts/mirrors/text.rst new file mode 100644 index 0000000..b42647e --- /dev/null +++ b/general-concepts/mirrors/text.rst @@ -0,0 +1,59 @@ +Mirrors +======= + +Automatic Mirroring +------------------- + +Packages will automatically have their ``SRC_URI`` components mirrored onto +Gentoo mirrors. When fetching, portage checks Gentoo mirrors first before +trying the original upstream location. + +This is generally desired behaviour -- upstream mirrors are prone to being +rearranged, tidied out or having files modified. + +Restricting Automatic Mirroring +''''''''''''''''''''''''''''''' + +Three ``RESTRICT`` keywords can be used to control the mirroring process. + +The ``RESTRICT="nomirror"`` setting should be used if we cannot legally mirror +certain files. + +The ``RESTRICT="primaryuri"`` setting causes portage to try +original locations *first*, and then fall back to mirrors if necessary -- this +is sometimes useful if approximate download counts are needed, or if upstream +have a reliable mirror setup. + +There is also ``RESTRICT="fetch"``, which prevents portage from trying to +fetch anything manually. The `pkg_nofetch`_ function will be called if any +``SRC_URI`` components cannot be found. This should only be used if a licence +requires it. + +Suitable Download Hosts +''''''''''''''''''''''' + +Hosting files off ``dev.gentoo.org`` is **not** acceptable for main-tree items. +Instead, these files must be moved onto ``mirror://gentoo`` before release. + +Gentoo Mirrors +-------------- + +To manually upload a file to ``mirror://gentoo``, ``scp`` it to +``dev.gentoo.org:/space/distfiles-local``. You must ensure that the permissions +are set to ``ug+rw`` manually. The file should appear on the mirrors within four +hours (note that this is *less frequent* than `CVS to rsync`_). + +If the upstream download location for a package uses a non-standard TCP port +(anything other than 21, 80 or 443), you *must* manually mirror the files. Not +doing so can cause all kinds of problems with strict firewalls. + +Mirroring Process +----------------- + +.. figure:: diagram.png + :alt: Mirroring Process + + Diagram showing the mirroring process + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/overlay/text.rst b/general-concepts/overlay/text.rst new file mode 100644 index 0000000..483a7b3 --- /dev/null +++ b/general-concepts/overlay/text.rst @@ -0,0 +1,35 @@ +Overlay +======= + +Portage can look in multiple places for packages by using an overlay. The +locations of overlays are controlled by the ``PORTDIR_OVERLAY`` variable, which +should contain a space-separated list of paths. + +The overlay should contain the same directory structure as ``PORTDIR`` (although +only the necessary directories need be included). For example, a simple overlay +might have a directory structure like: :: + + overlay + |-- dev-util + `-- gengetopt + |-- Manifest + |-- files + | `-- digest-gengetopt-2.13 + `-- gengetopt-2.13.ebuild + +An overlay can be used to 'add' items to the tree (although you must ensure that +``/etc/portage/categories`` is used if any new categories are added) or to +override existing entries. + +Overlay and Eclasses +-------------------- + +Be very careful when using eclasses in an overlay. Portage will not do cache +updates when an overlay eclass is changed, nor will it do cache updates when a +main portage tree eclass which is used by an overlay ebuild changes. You may +also encounter bogus 'illegal inherit' notices when working with eclasses in +overlay (see `QA Notice -- ECLASS foo inherited illegally`_). To be safe, +manually ``touch`` all relevant overlay files after updating overlay eclasses. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/pic/text.rst b/general-concepts/pic/text.rst new file mode 100644 index 0000000..fdd31a4 --- /dev/null +++ b/general-concepts/pic/text.rst @@ -0,0 +1,9 @@ +Position Independent Code +========================= + +.. Todo:: policy. http://www.gentoo.org/proj/en/hardened/pic-internals.xml has + some technical details. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/general-concepts/portage-cache/bad-cache-dep-sample.ebuild b/general-concepts/portage-cache/bad-cache-dep-sample.ebuild new file mode 100644 index 0000000..bf9cd1c --- /dev/null +++ b/general-concepts/portage-cache/bad-cache-dep-sample.ebuild @@ -0,0 +1,8 @@ +# HEADER + +# DO NOT DO THIS! +if ! has_version "x11-libs/gtk+" ; then + DEPEND="${DEPEND} + gtk2? ( >=x11-libs/gtk+-2 ) + !gtk2? ( =x11-libs/gtk+-1.2* )" +fi diff --git a/general-concepts/portage-cache/conditional-inherit.ebuild b/general-concepts/portage-cache/conditional-inherit.ebuild new file mode 100644 index 0000000..34fa096 --- /dev/null +++ b/general-concepts/portage-cache/conditional-inherit.ebuild @@ -0,0 +1,5 @@ +# header + +if [[ "${PN##*-}" == "cvs" ]] ; then + inherit cvs +fi diff --git a/general-concepts/portage-cache/good-cache-dep-sample.ebuild b/general-concepts/portage-cache/good-cache-dep-sample.ebuild new file mode 100644 index 0000000..d4473bc --- /dev/null +++ b/general-concepts/portage-cache/good-cache-dep-sample.ebuild @@ -0,0 +1,17 @@ +# Header + +inherit versionator + +if [[ $(get_major_version ) -ge 7 ]] ; then + IUSE="${IUSE} tcltk mzscheme" + DEPEND="$DEPEND + tcltk? ( dev-lang/tcl ) + mzscheme? ( dev-lisp/mzscheme )" + RDEPEND="$RDEPEND + tcltk? ( dev-lang/tcl ) + mzscheme? ( dev-lisp/mzscheme )" + + if [[ "${MY_PN}" != "vim-core" ]] ; then + RDEPEND="${RDEPEND} !<app-vim/align-30-r1" + fi +fi diff --git a/general-concepts/portage-cache/text.rst b/general-concepts/portage-cache/text.rst new file mode 100644 index 0000000..abb77f8 --- /dev/null +++ b/general-concepts/portage-cache/text.rst @@ -0,0 +1,33 @@ +The Portage Cache +================== + +Portage uses a cache for most top-level variables (``DEPEND``, ``DESCRIPTION``, +``SRC_URI`` and so on). This cache may be generated on a different machine, so +these variables must be either static or generated using only unchanging +'version / name' variables (``P``, ``PN``, ``PV``, ``PR``, ``PVR`` and ``PF``). + +So, the following will not work: + +.. CODESAMPLE bad-cache-dep-sample.ebuild + +However, this is legal, since ``versionator.eclass`` works upon ``PV``, and +``PV`` and ``PN`` are both static: + +.. CODESAMPLE good-cache-dep-sample.ebuild + +Conditional Inherits +-------------------- + +Because eclasses modify various cached variables, conditional inheritance is not +allowed except where the same results will always be obtained on every system. +For example, inherits based upon USE flags are illegal, but inherits based +solely upon ``PN`` are allowed. + +As an example of a legal and possibly useful conditional inherit, some eclasses +do: + +.. CODESAMPLE conditional-inherit.ebuild + +This allows the same eclass to be used for both regular and ``-cvs`` packages. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/general-concepts/privileges/text.rst b/general-concepts/privileges/text.rst new file mode 100644 index 0000000..4c0c62d --- /dev/null +++ b/general-concepts/privileges/text.rst @@ -0,0 +1,9 @@ +Privileges +========== + +.. Todo:: general privs stuff, include stuff on setuid/setgid and sticky since + a lot of people seem to be confused about those... Also notes on the portage + user and group issues, and what we use for root:root to make \*bsd work. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/sandbox/text.rst b/general-concepts/sandbox/text.rst new file mode 100644 index 0000000..e40ea01 --- /dev/null +++ b/general-concepts/sandbox/text.rst @@ -0,0 +1,20 @@ +Sandbox +======= + +During the ``src_unpack``, ``src_compile``, ``src_test`` and ``src_install`` +phases, ``ebuild.sh`` operates inside a *sandbox*. This is a special environment +which attempts to help prevent badly written ebuilds (or ebuilds working with +badly written build systems) accidentally writing outside of permitted locations. + +**All packages must build correctly when sandbox is active.** Packages must not +achieve this by using sneaky tricks to make sandbox warnings not show up -- the +sandbox is there to ensure that binary packages will work correctly, and that +a badly written ``Makefile`` won't cause problems. Using ``addwrite`` is +generally **not** the correct solution. + +See `Sandbox Functions Reference`_ for details on sandbox-related functions. See +`Handling Access Violations`_ for suggestions on fixing sandbox-related build +problems. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/slotting/text.rst b/general-concepts/slotting/text.rst new file mode 100644 index 0000000..f9e9735 --- /dev/null +++ b/general-concepts/slotting/text.rst @@ -0,0 +1,34 @@ +Slotting +======== + +Packages can support having multiple versions installed simultaneously. This is +useful for libraries which may have changed interfaces between versions -- for +example, the ``gtk+`` package can install both versions ``1.2`` and ``2.6`` in +parallel. This feature is called slotting. + +Most packages have no need for slotting. These packages specify ``SLOT="0"`` in +the ebuilds. This is **not** the same as specifying an empty slot -- an empty +slot means "disable slotting entirely", and should not be used. + +Portage permits at most one instance of a package installation *per ``SLOT`` +value*. For example, say we have the following: + +* ``foo-1.1`` with ``SLOT="1"`` +* ``foo-1.2`` with ``SLOT="1"`` +* ``foo-2.0`` with ``SLOT="2"`` +* ``foo-2.1`` with ``SLOT="2"`` + +Then the user could have, say, ``foo-1.2`` and ``foo-2.0`` installed in +parallel, but *not* ``foo-1.1`` and ``foo-1.2``. Note that it is entirely +possible that the user may have ``foo-2.0`` installed and no ``foo-1.x`` at all. + +It is not possible to ``DEPEND`` upon a package in a specific slot. + +Currently portage will accept an arbitrary string for the value of ``SLOT``. For +future compatibility, it is recommended that slots contain only characters which +are allowed in an ebuild name or version (alphanumerics, hypens, full stops, +underscores, the plus character) -- other characters may cause problems with +future portage enhancements. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/text.rst b/general-concepts/text.rst new file mode 100644 index 0000000..6057889 --- /dev/null +++ b/general-concepts/text.rst @@ -0,0 +1,9 @@ +General Concepts +================ + +This section covers some general concepts with which you should be familiar when +writing ebuilds or working with the portage tree. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/general-concepts/tree/text.rst b/general-concepts/tree/text.rst new file mode 100644 index 0000000..84974d2 --- /dev/null +++ b/general-concepts/tree/text.rst @@ -0,0 +1,121 @@ +The Portage Tree +================ + +The basic layout of the portage tree is as follows: + +* Categories, for example ``app-editors``, ``sys-apps`` + + + Category metadata, for example ``app-admin/metadata.xml`` + + + Package directories for example ``app-editors/vim`` + + - Package metadata, for example ``app-editors/vim/metadata.xml`` + + - Package changelog, for example ``app-editors/vim/ChangeLog`` + + - Package Manifest, for example ``app-editors/vim/Manifest`` + + - Ebuilds, for example ``app-editors/vim/vim-6.3.068.ebuild``, + ``app-editors/vim/vim-7.0_alpha20050326.ebuild`` + + - Package files directory, for example ``app-editors/vim/files`` + + * Digest files, for example + ``app-editors/vim/files/digest-vim-6.3.068``, + ``app-editors/vim/files/digest-vim-7.0_alpha20050326`` + + * Small patches and other miscellaneous files, for example + ``app-editors/vim/files/vim-completion`` + +* Eclasses directory, ``eclass/`` + +* Licenses directory, ``licenses/`` + +* Profiles directory, ``profiles/`` + + + Various control and documentation files, for example ``categories``, + ``info_pkgs``, ``info_vars``, ``package.mask``, ``use.desc`` + + + Updates directory, ``profiles/updates/`` + + - Updates files, for example ``profiles/updates/1Q-2005`` + + + Main profile cascade + +* Scripts directory, ``scripts/`` + +* Distfiles directory, ``distfiles/``. This is not included in the main CVS + tree, but it will be found on most user systems. + +* Packages directory, ``packages``. Again, this is found on user systems but not + in the main CVS tree. + +What Belongs in the Tree? +------------------------- + +Things that do **not** belong in the tree: + +* Large patches +* Non-text files +* Photos of teletubbies +* Files whose name starts with a dot + +Software-wise, in general all of the following should be met in order for a +package to be included in the tree: + +Active, Cooperative Upstream + If a package is undeveloped or unmaintained upstream, it can be extremely + difficult to get problems fixed. If a package does not have an active + upstream, the developers who add the package to the tree must ensure that + they are able to fix any issues which may arise. + + Sometimes upstream may have a reason for not wanting their package included + in the tree. This should be respected. + +Reasonably Stable + Keep super-experimental things out of the tree. If you must commit them, + consider using ``package.mask`` until things calm down, or better yet make + them available as overlay ebuilds. + +Reasonably Useful + Don't feel obliged to include "Joe's '1337 XMMS Skinz Collection" or "Hans' + Super Cool Fast File System" in the tree just because a few users ask for + it. Stick to things that might actually be of use. + +Properly Packaged + If something is only available in live CVS or dodgy autopackage format, + don't include it until upstream can come up with a decent source package. + Similarly, avoid things that don't have a proper build system (where + relevant) -- these are very tricky to maintain. + +Patching and Distribution Permitted + If we can't patch packages as necessary ourselves, we end up relying + entirely upon upstream for support. This can be problematic, especially if + upstream are slow at fixing things. We don't want to be in the situation + where we can't stable a critical package because we're still waiting for a + closed-source vendor to get their act together. + + Similarly, not being able to mirror and distribute tarballs ourselves makes + us rely entirely upon upstream mirrors. Experience has shown that these are + often extremely unreliable, with files changing, moving or vanishing at + random. + +Working Ebuilds + If you don't have a *working* ebuild, don't include it. + +Portable + If software is unportable, it's generally because it's badly written. + Remember that although x86 has a market majority *now*, it probably won't in + the not too distant future once x86-64 catches on. + +Reasonable Security Record + Don't include software that has a terrible security record. Each + vulnerability is a *lot* of work for a lot of people (security teams, arch + teams and package maintainers). + +Obviously, sometimes exceptions are necessary. We include PHP in the tree +*despite* its security record, for example, because it's a popular package and +we're 'expected' to have it. These are merely guidelines. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/general-concepts/use-flags/conflicting-flags.ebuild b/general-concepts/use-flags/conflicting-flags.ebuild new file mode 100644 index 0000000..29b9905 --- /dev/null +++ b/general-concepts/use-flags/conflicting-flags.ebuild @@ -0,0 +1,20 @@ +# Header + +src_compile() { + local myconf + + if use ssl && use gnutls ; then + myconf="${myconf} --enable-ssl --with-ssl=gnutls" + elif use ssl && ! use gnutls ; then + myconf="${myconf} --enable-ssl --with-ssl=openssl" + else + myconf="${myconf} --disable-ssl" + fi + + econf \ + # Other stuff + ${myconf} \ + || die "configure failed + + emake || die "make failed" +} diff --git a/general-concepts/use-flags/noblah-1.ebuild b/general-concepts/use-flags/noblah-1.ebuild new file mode 100644 index 0000000..07618e4 --- /dev/null +++ b/general-concepts/use-flags/noblah-1.ebuild @@ -0,0 +1,3 @@ +# Header + +RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )" diff --git a/general-concepts/use-flags/noblah-2.ebuild b/general-concepts/use-flags/noblah-2.ebuild new file mode 100644 index 0000000..b653ce5 --- /dev/null +++ b/general-concepts/use-flags/noblah-2.ebuild @@ -0,0 +1,3 @@ +# Header + +DEPEND="!sparc? ( !alpha? ( alsa? ( media-libs/alsa-lib ) ) )" diff --git a/general-concepts/use-flags/noblah-3.ebuild b/general-concepts/use-flags/noblah-3.ebuild new file mode 100644 index 0000000..bbcaefa --- /dev/null +++ b/general-concepts/use-flags/noblah-3.ebuild @@ -0,0 +1,3 @@ +# Header + +RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )" diff --git a/general-concepts/use-flags/noblah-4.ebuild b/general-concepts/use-flags/noblah-4.ebuild new file mode 100644 index 0000000..5676176 --- /dev/null +++ b/general-concepts/use-flags/noblah-4.ebuild @@ -0,0 +1,3 @@ +# Header + +RDEPEND="!noalsa? ( media-libs/alsa )" diff --git a/general-concepts/use-flags/text.rst b/general-concepts/use-flags/text.rst new file mode 100644 index 0000000..98f205c --- /dev/null +++ b/general-concepts/use-flags/text.rst @@ -0,0 +1,130 @@ +USE Flags +========= + +USE flags are to control *optional* dependencies and settings which the user may +reasonably want to select. For example, ``vim`` can optionally build with +support for the ``ruby`` interpreter, and it needs ``ruby`` installed to do this +-- we use the ``ruby`` USE flag to provide this option. On the other hand, +``glark`` requires ``ruby`` no matter what, so no USE flag is used here. + +No combination of USE flags should cause a package to fail to build. + +Packages should not configure and link based upon what is available at compile +time -- any autodetection must be overridden. + +``noblah`` USE Flags +-------------------- + +If at all possible, avoid ``noblah`` style USE flags. These break ``use.mask`` +and cause all sorts of complications for arch developers. Here's why: + +Consider a hypothetical package named 'vplayer', which plays videos. This +package has optional support, via USE flags, for various sound and video output +methods, various video codecs and so on. + +One of vplayer's optional features is support for the 'fakemedia' codec, which +is unfortunately only available as a dodgy x86 binary. We *could* handle this by +doing something like: + +.. CODESAMPLE noblah-1.ebuild + +Except this is pretty nasty -- what happens when an amd64 binary is made as +well? Also, users on other archs will see fakemedia listed in ``emerge -pv`` +output, even though it is not actually available. + +Similarly, say vplayer supports output via the ALSA codec as one option. +However, ALSA isn't (or wasn't when this example was written) available on sparc +or alpha. So we could do: + +.. CODESAMPLE noblah-2.ebuild + +Again, it's messy, and alsa still shows up in the ``emerge -pv`` output. Also, +once ALSA starts working on sparc, every ebuild that does this would have to be +manually edited. + +The solution is ``use.mask``, which is documented in `Profiles use.mask File`_. +Each profile can have a ``use.mask`` file which can be used to forcibly disable +certain USE flags on a given arch (or subarch, or subprofile). So, if the +``fakemedia`` USE flag was use.masked on every non-x86 profile, the following +would be totally legal and wouldn't break anything: + +.. CODESAMPLE noblah-3.ebuild + +Users of non-x86 would see the following when doing ``emerge -pv vplayer``: :: + + [ebuild R ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz + +To get a flag added to ``use.mask``, ask the relevant arch team. + +So what's the problem with ``noblah`` flags? + +There's no way to forcibly *enable* a given USE flag on a particular profile. +So, something like: + +.. CODESAMPLE noblah-4.ebuild + +will make your package unusable by archs without ALSA support, and there is no +way to fix it that doesn't involve adding in nasty ``arch?`` flags. + +Local and Global USE Flags +-------------------------- + +USE flags are categorised as either local or global. A global USE flag must +satisfy several criteria: + + * It is used by many different packages. + * It has a general non-specific purpose. + +The second point is important. If the effect of the ``thing`` USE flag upon +``pkg-one`` is substantially different from the effect it has upon ``pkg-two``, +then ``thing`` is not a suitable candidate for being made a global flag. In +particular, note that if ``client`` and ``server`` USE flags are ever +introduced, they can not be global USE flags for this reason. + +Before introducing a new global USE flag, it must be discussed on the gentoo-dev +mailing list. + +USE Flag Descriptions +--------------------- + +All USE flags (excluding ``USE_EXPAND`` flags) must be described in either +``use.desc`` or ``use.local.desc`` in the ``profiles/`` directory. See +`portage-5`_ or the comments in these files for an explanation of the format. +Remember to keep these files sorted. + +Conflicting USE Flags +--------------------- + +Occasionally, ebuilds will have conflicting USE flags for functionality. +Checking for them and returning an error is *not* a viable solution. Instead, +you must pick one of the USE flags in conflict to favour. + +One example comes from the ``msmtp`` ebuilds. The package can use either SSL +with GnuTLS, SSL with OpenSSL, or no SSL at all. Because GnuTLS is more +featureful than OpenSSL, it is favoured: + +.. CODESAMPLE conflicting-flags.ebuild + +USE_EXPAND and ARCH USE Flags +----------------------------- + +The ``VIDEO_CARDS``, ``INPUT_DEVICES`` and ``LINGUAS`` variables are +automatically expanded into USE flags. These are known as ``USE_EXPAND`` +variables. If the user has ``LINGUAS="en fr"`` in ``make.conf``, for example, +then ``USE="linguas_en linguas_fr"`` will automatically be set by portage. + +The ``USE_EXPAND`` list is set in ``profiles/base/make.defaults`` as of Portage +2.0.51.20. This must not be modified without discussion on the gentoo-dev list, +and it must not be modified in any subprofile. + +The current architecture (eg ``x86``, ``sparc``, ``ppc-macos``) will +automatically be set as a USE flag as well. See ``profiles/arch.list`` for a +full list of valid architecture keywords, and `GLEP 22`_ for an explanation of +the format. + +.. Warning:: It is a common misconception that the architecture variable is somehow + related to ``ACCEPT_KEYWORDS``. It isn't. Accepting ``x86`` keywords on + ``sparc``, for example, won't set ``USE="x86"``. Similarly, there are no + ``~arch`` USE flags, so don't try ``if use ~x86``. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/general-concepts/user-environment/filtering-1.ebuild b/general-concepts/user-environment/filtering-1.ebuild new file mode 100644 index 0000000..225e368 --- /dev/null +++ b/general-concepts/user-environment/filtering-1.ebuild @@ -0,0 +1,8 @@ +# Header + +pkg_setup() { + # Unset all locale related variables, they can make the + # build fail. + + eval unset ${!LC_*} LANG +} diff --git a/general-concepts/user-environment/text.rst b/general-concepts/user-environment/text.rst new file mode 100644 index 0000000..8a4a11e --- /dev/null +++ b/general-concepts/user-environment/text.rst @@ -0,0 +1,53 @@ +User Environment +================ + +User environment variables and ``make.conf`` settings get passed on to ebuilds. +This can be useful -- it's how ``CFLAGS`` and friends work, for example -- but +it can also result in nasty build-breaking variables like ``LANG`` and +``LC_ALL`` getting through. Currently no sanitisation is performed upon the +environment. + +Filtering Variables +------------------- + +Certain variables will really really upset certain build systems. A good example +is the locale variables (``LC_ALL`` et al), which if set to certain values will +cause ``sed`` or ``grep`` expressions involving the likes of ``[A-Z]`` to fail. +The easiest thing to do here is to ``unset`` or sanitise the offending variables +inside ``pkg_setup``. + +The simplest way to unset all locale-related variables is: + +.. CODESAMPLE filtering-1.ebuild + +Not Filtering Variables +----------------------- + +On the other hand, it is extremely important that certain user preferences are +honoured as far as possible. A good example is ``CFLAGS``, which *must* be +respected (selective filtering is fine, but outright ignoring is not). Ignoring +``CFLAGS`` when compiling can cause serious problems: + +* Ignoring ``march/mcpu`` may force kernel or software emulation for certain + opcodes on some architectures. This can be *very* slow -- for example, + ``openssl`` built for SPARC v7 but run on v9 is around five times slower for + RSA operations. + +* Stripping certain ABI-related flags will break linkage. + +* Stripping certain ABI-related flags will result in invalid code being produced + for certain setups. In extreme cases, we could end up with daft things like + big endian code being produced for little endian CPUs. + +* If a user's ``march/mcpu/mtune`` is ignored, and an auto-detected setting is + used instead, GRP and stages will break. For example, ``i686`` stages could no + longer be produced on a ``pentium-4``, and ``v8`` stages could no longer be + produced on an ``UltraSparc``. + +Some packages do this by accident. For example, one might see +``CFLAGS=-Wall`` in ``Makefile.am``. To fix this, either ``sed`` in the user's +``CFLAGS``, or (the better solution) change the variable to ``AM_CFLAGS``, which +will automatically be merged with the user's settings. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/hosted-projects/text.rst b/hosted-projects/text.rst new file mode 100644 index 0000000..e716600 --- /dev/null +++ b/hosted-projects/text.rst @@ -0,0 +1,86 @@ +Hosted Projects +=============== + +The following guidelines have been proposed for hosted projects in an attempt to +prevent a repeat of the ``genkernel`` disaster. + +Documentation Requirement +------------------------- + +All hosted projects should have decent, up to date user and developer +documentation. This documentation must be available *before the first release*, +and not left as "something we'll do later (honest)". + +Our documentation team are happy to help out with GuideXMLification, translation +etc. for the user documentation, but they *need* various things to do this: + ++ Basic documentation to start with. ++ Basic information on the project or tool, such as: + + * The goals + * The design specification + * An FAQ + ++ To be informed of any updates, in advance if at all possible -- this is to + avoid having out of date recommendations in the documentation. + +Developer documentation is generally best left in the hands of the project +maintainers. + +Portability +----------- + +Gentoo runs on a large number of architectures. This is one of our big +advantages over some other distributions. It is therefore important that any +tools are made with portability in mind, *even if you originally think that your +tool is only relevant for one arch*. It was this kind of assumption that meant +that ``genkernel`` had to be completely rewritten when it suddenly became +mandatory. + +In practice, this means the following: + +* Using a portable programming language -- no Java or C# for any Gentoo tools. + Bash, C and Python are good, especially since everyone already has those + installed. + +* Not making assumptions about the hardware or architecture. This covers various + things, depending upon the tool -- simple examples include: + + + Not assuming that you are running on a 32bit little endian system. + + Not assuming that all computers have a VGA text console, or indeed any + kind of graphics capability. + + Not assuming that all computers use DOS disclabels. + +* Not relying too strongly upon particular implementations of various tools, + except where it has been agreed that we will always use a particular + implementation of said tool (it is safe to use ``GNU sed`` extensions, for + example, but *not* ``GNU find`` extensions). + +Open / Free +----------- + +All hosted projects should use an appropriate open / free / libre licence. +Typically this will be the GPL v2 for software, and the Creative Commons licence +for documentation. However, reasonable exceptions can be made -- sometimes it +makes more sense to use the LGPL or a \*BSD licence, and for application-specific +projects going with the application's licence may make more sense (the +``gentoo-syntax`` package for ``vim`` uses the ``vim`` licence, for example). + +Accessible +---------- + +Projects should be accessible to users with disabilities. Simple examples of how +to go about this include: + ++ Not relying solely upon colour to convey information. ++ Providing textual descriptions for any images. ++ Providing clear captions for dialogs, buttons, form fields and so on. + +Good places to look for further hints include: + ++ The `GNOME Accessibility Project <http://developer.gnome.org/projects/gap/>`_ ++ The `W3C Web Accessibility Initiative Guidelines + <http://www.w3.org/WAI/Resources/#gl>`_. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/index/text.rst b/index/text.rst new file mode 100644 index 0000000..22690c9 --- /dev/null +++ b/index/text.rst @@ -0,0 +1,7 @@ +Index +===== + +.. INDEX + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/keywording/keywording-1.ebuild b/keywording/keywording-1.ebuild new file mode 100644 index 0000000..e675e60 --- /dev/null +++ b/keywording/keywording-1.ebuild @@ -0,0 +1,3 @@ +# Headers. + +KEYWORDS="x86 sparc mips ~ppc ~ppc-macos -ia64" diff --git a/keywording/keywording-2.ebuild b/keywording/keywording-2.ebuild new file mode 100644 index 0000000..2f1f4b8 --- /dev/null +++ b/keywording/keywording-2.ebuild @@ -0,0 +1,3 @@ +# Headers. + +KEYWORDS="-* x86 ppc" diff --git a/keywording/text.rst b/keywording/text.rst new file mode 100644 index 0000000..307bf98 --- /dev/null +++ b/keywording/text.rst @@ -0,0 +1,172 @@ +Keywording +========== + +.. Note:: Terminology + The term 'package' refers to an entire directory, for example + ``app-editors/vim`` -- it does *not* refer to a specific version. The terms + 'ebuild' or 'package version' are used when this meaning is intended. This + distinction is important. + +Every ebuild should specify a ``KEYWORDS`` variable. This variable is used to +indicate the suitability and stability of both the package and the ebuild on +each given arch (``sparc``, ``ppc``, ``x86-obsd``...). + +.. Note:: The term 'arch' is used in this sense for historical reasons. As a result + of `GLEP 22`_ and the various non-Linux ports, this is no longer a particularly + accurate term. + +A sample ``KEYWORDS`` entry might look like: + +.. CODESAMPLE keywording-1.ebuild + +The different levels of keyword are: + +``arch`` (``x86``, ``ppc-macos``) + Both the package version *and* the ebuild are widely tested, known to work + and not have any serious issues on the indicated platform. + +``~arch`` (``~x86``, ``~ppc-macos``) + The package version and the ebuild are believed to work and do not have any + known serious bugs, but more testing is required before the package version + is considered suitable for ``arch``. + +No keyword + If a package has no keyword for a given arch, it means it is not known + whether the package will work, or that insufficient testing has occurred for + ``~arch``. + +``-arch`` (``-x86``, ``-ppc-macos``) + The package version will not work on the arch. This could be caused by badly + written code (for example, non-64-bit or endian clean code), relying upon + particular hardware (for example, a BIOS querying tool would not work on + non-BIOS architectures) or binary only packages. + +The ``-*`` keyword is special. It is used to indicate package versions which are +not worth trying to test on unlisted archs. For example, a binary-only package +which is only supported upstream on ``x86`` and ``ppc`` might use: + +.. CODESAMPLE keywording-2.ebuild + +This is different in implication from ``"x86 ppc"`` -- the former implies that +it will not work on other archs, whereas the latter implies that it has not been +tested. + +Do **not** use the ``*`` or ``~*`` special keywords in ebuilds. + +Equal Visibility Requirement +---------------------------- + +An ebuild **must not** depend upon any package that is of a lower keyword level +than itself. For example, if ``foo-1.2`` depends upon ``bar-1.2``, and +``bar-1.2`` is ``~x86``, then ``foo-1.2`` must **not** be marked stable on +``x86`` unless ``bar-1.2`` is also stabilised. + +You may assume that if a user accepts ``~arch`` for a given arch then they also +accept ``arch``. + +For optional dependencies, all *possible* dependencies must satisfy the above. +Note that certain ``USE`` flags can be forcibly disabled on a per-profile basis +-- talk to the arch teams if you require this. For either-or dependencies, *at +least one* of the options must be of equal or better visibility than the +package in question. + +Hard Masks +---------- + +The ``package.mask`` file can be used to 'hard mask' individual or groups of +ebuilds. This should be used for testing ebuilds or beta releases of software, +and may also be used if a package has serious compatibility problems. Packages +which are not hard masked must **not** have a dependency upon hard masked +packages. + +The only time it is acceptable for a user to see the ``Possibly a DEPEND +problem`` error message is if they have manually changed visibility levels for a +package (for example, through ``/etc/portage/``) and have missed a dependency. +**You should never commit a change which could cause this error to appear on a +user system**. + +Keywording New Packages +----------------------- + +.. Important:: New packages should be marked as ``~arch`` only upon + architectures for which the committing developer has tested. + +Do **not** assume that your package works on all architectures. Do **not** +assume that user submitted ebuilds will have correct ``KEYWORDS`` -- chances are +they just copied from somewhere else. Do **not** assume that upstream's +'supported architectures' list is correct. Do **not** assume that because your +code is written in Perl / Python / Java / whatever that it will run on other +archs (there is at least one case of a ``vim`` script which only worked on +``x86``). + +Note that most (non-x86) archs expect you to be on the arch team and bugzilla +alias if you are committing packages with keywords for that arch, and may have +additional requirements of which you should be aware (on ``mips``, for example, +there are multiple ABIs and byte orders to consider -- a package working on your +``o32`` box may not work on ``o64`` or ``n32``). Contact the individual arch +teams for details. + +Do **not** commit straight to ``arch``. + +Keywording on Upgrades +---------------------- + +When upgrading, drop all existing keywords from ``arch`` to ``~arch``, and leave +any existing ``~arch`` keywords intact. This must be done even if you *think* +you're just making a trivial fix -- there have been several examples of the +stable tree getting broken this way. + +Sometimes you may need to remove a keyword because of new unresolved +dependencies. If you do this, you **must** file a bug notifying the relevant +arch teams. + +This also applies to revision bumps, not just to upstream version changes. + +Moving from ``~arch`` to ``arch`` +--------------------------------- + +With the exception of ``x86``, moving a package from ``~arch`` to ``arch`` is +done only by the relevant arch teams. If you have access to non-x86 but are not +on the arch teams, you may wish to make individual arrangements -- the arch +teams are happy for help, so long as they know what is going on. + +For a package to move to stable, the following guidelines must be met: + +* The package has spent a reasonable amount of time in ``~arch`` first. Thirty + days is the usual figure, although this is clearly only a guideline. For + critical packages, a much longer duration is expected. For small packages + which have only minor changes between versions, a shorter period is sometimes + appropriate. + +* The package must not have any non-``arch`` dependencies. + +* The package must not have any severe outstanding bugs or issues. + +* The package must be widely tested. + +* If the package is a library, it should be known not to break any package which + depends upon it. + +* (Excluding x86) the relevant arch team must agree to it. + +For security fixes, the "reasonable amount of time" guideline may be relaxed. +See the `Vulnerability Treatment Policy +<http://www.gentoo.org/security/en/vulnerability-policy.xml>`_. + +Removing Package Versions +------------------------- + +When removing ebuild, ensure that you do not remove the most recent version at +any given keyword level on any profile. The aim here is: + +* Never to force a downgrade. (Exception: occasionally you really do want to + force a downgrade, for example if the newly committed ``foo-1.3`` turns out + to be badly broken and that making everyone downgrade to ``foo-1.2`` is the + better option. This is rare.) + +* Do not break any existing dependencies. + +If you would like a particular package version moved to stable on certain archs +so that you can tidy up, file a bug. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/profiles/categories/text.rst b/profiles/categories/text.rst new file mode 100644 index 0000000..3df4874 --- /dev/null +++ b/profiles/categories/text.rst @@ -0,0 +1,13 @@ +Profiles ``categories`` File +============================ + +The ``profiles/categories`` file contains an asciibetically sorted list of all +the valid categories in the portage tree. When adding a new category, remember +to update and commit this file *before* making any related commits. + +The ``categories`` file is a straight list. For descriptions, see `Category +Metadata`_. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/profiles/info_files/text.rst b/profiles/info_files/text.rst new file mode 100644 index 0000000..39db2d0 --- /dev/null +++ b/profiles/info_files/text.rst @@ -0,0 +1,9 @@ +Profiles ``info_`` Files +======================== + +The ``profiles/info_pkgs`` file controls the packages whose versions are listed +when ``emerge info`` is run. The ``profiles/info_vars`` file controls the +displayed environment variables. Do not add to these files without discussion on +the ``gentoo-dev`` mailing list. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/profiles/make.defaults/text.rst b/profiles/make.defaults/text.rst new file mode 100644 index 0000000..6e866c0 --- /dev/null +++ b/profiles/make.defaults/text.rst @@ -0,0 +1,13 @@ +Profiles ``make.defaults`` File +=============================== + +The ``make.defaults`` file in ``profiles/`` provides a minimal set of defaults +for the kinds of values which may be set in ``make.conf`` (``CFLAGS``, ``USE``, +``FEATURES`` etc) along with certain control variables (eg ``USE_EXPAND``). +These values can further be refined by additional ``make.defaults`` files in +subprofiles. + +In general, ``make.defaults`` should not be modified without consulting the +relevant arch team, or ``gentoo-dev`` for high-up ``make.defaults`` files. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/profiles/package.mask/text.rst b/profiles/package.mask/text.rst new file mode 100644 index 0000000..f176e98 --- /dev/null +++ b/profiles/package.mask/text.rst @@ -0,0 +1,11 @@ +Profiles ``package.mask`` File +============================== + +The ``package.mask`` file can be used to hard mask packages or certain versions +of packages. This is often used when adding certain experimental (either in +ebuild or upstream terms) packages to the tree. The format is described in +`portage-5`_. + +This file can be used in subprofiles to mask packages only for certain setups. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/profiles/packages/text.rst b/profiles/packages/text.rst new file mode 100644 index 0000000..e5c3427 --- /dev/null +++ b/profiles/packages/text.rst @@ -0,0 +1,9 @@ +Profiles ``packages`` File +========================== + +The ``packages`` file in ``profiles/`` controls the packages pulled in by the +``system`` target. The ``base/packages`` file must not be modified without +discussion on the ``gentoo-dev`` list; subprofile overrides are up to the +relevant arch teams. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/profiles/profiles.desc/text.rst b/profiles/profiles.desc/text.rst new file mode 100644 index 0000000..dae6ea4 --- /dev/null +++ b/profiles/profiles.desc/text.rst @@ -0,0 +1,8 @@ +Profiles ``profiles.desc`` File +=============================== + +.. Todo:: find someone who knows exactly what this file's really used for with + current portage versions and what is and isn't allowed. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/profiles/text.rst b/profiles/text.rst new file mode 100644 index 0000000..72d3055 --- /dev/null +++ b/profiles/text.rst @@ -0,0 +1,10 @@ +Profiles +======== + +This section provides details on the ``profiles/`` directory. All of these files +are also documented in `portage-5`_. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/profiles/updates/text.rst b/profiles/updates/text.rst new file mode 100644 index 0000000..3f74b8a --- /dev/null +++ b/profiles/updates/text.rst @@ -0,0 +1,7 @@ +Profiles ``updates/`` Directory +=============================== + +.. Todo:: move and slotmove + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/profiles/use.desc/text.rst b/profiles/use.desc/text.rst new file mode 100644 index 0000000..1980578 --- /dev/null +++ b/profiles/use.desc/text.rst @@ -0,0 +1,18 @@ +Profiles ``use.desc`` and ``use.local.desc`` Files +================================================== + +The ``use.desc`` file contains a list of all global non-expanded ``USE`` flags, +together with a short description. This file should not be modified without +discussion on the ``gentoo-dev`` list. + +The ``use.local.desc`` file contains a list of all local ``USE`` flags, together +with the relevant packages, and a short description. This file can be added to +without general discussion. + +Having a small number of packages using identically named local ``USE`` flags is +allowed. If the number starts to grow substantially, it may be worth proposing +that the flag becomes a global -- see `Local and Global USE Flags`_. + +All non-expand flags must be listed in exactly one of these files. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/profiles/use.mask/text.rst b/profiles/use.mask/text.rst new file mode 100644 index 0000000..dc52d8d --- /dev/null +++ b/profiles/use.mask/text.rst @@ -0,0 +1,27 @@ +Profiles ``use.mask`` File +========================== + +The ``use.mask`` file can be used to mark ``USE`` flags as unavailable on a +particular profile. This can be useful for various reasons: + +* Masking hardware-specific feature flags. For example, ``mmx`` and ``sse`` are + only available on x86, ``altivec`` is only available on ``ppc`` and ``vis`` is + only available on sparc v9. + +* Disabling unavailable soft dependencies. A simple hypothetical example -- say + ``fooapp`` works on ``mips``, but has an optional dependency (controlled by + the ``bar`` flag) upon ``libbar``, which doesn't work on ``mips``. Then by + adding the ``bar`` flag to ``profiles/default-linux/mips/use.mask``, + ``fooapp`` could be made available to ``mips`` users with the unresolvable + dependency forcibly disabled. + +Note that ``use.mask`` is a per-flag thing, not per package's use of a given +flag. This is one of the reasons that USE flags must have a specific well +defined purpose. + +Updates to ``use.mask`` should be handled via the relevant arch team. + +See `noblah USE Flags`_ for more discussion. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/profiles/virtuals/text.rst b/profiles/virtuals/text.rst new file mode 100644 index 0000000..a065379 --- /dev/null +++ b/profiles/virtuals/text.rst @@ -0,0 +1,10 @@ +Profiles ``virtuals`` Files +=========================== + +The ``virtuals`` files in ``profiles/`` control the default provider for +virtuals. It can be overridden in subprofiles for profile-specific defaults. + +Before adding a new virtual, it should be discussed on ``gentoo-dev``. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/quickstart/ex1.ebuild b/quickstart/ex1.ebuild new file mode 100644 index 0000000..31c878d --- /dev/null +++ b/quickstart/ex1.ebuild @@ -0,0 +1,26 @@ +# Example + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +DESCRIPTION="Exuberant ctags generates tags files for quick source navigation" +HOMEPAGE="http://ctags.sourceforge.net" +SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz" + +LICENSE="GPL-2" +SLOT="0" +KEYWORDS="~mips ~sparc ~x86" +IUSE="" + +src_compile() { + econf --with-posix-regex || die "econf failed" + emake || die "emake failed" +} + +src_install() { + make DESTDIR="${D}" install || die "install failed" + + dodoc FAQ NEWS README + dohtml EXTENDING.html ctags.html +} diff --git a/quickstart/ex2.ebuild b/quickstart/ex2.ebuild new file mode 100644 index 0000000..5f2dd94 --- /dev/null +++ b/quickstart/ex2.ebuild @@ -0,0 +1,29 @@ +# Example + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +DESCRIPTION="detox safely removes spaces and strange characters from filenames" +HOMEPAGE="http://detox.sourceforge.net/" +SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2" + +LICENSE="BSD" +SLOT="0" +KEYWORDS="~hppa mips sparc x86" +IUSE="" + +DEPEND="dev-libs/popt + sys-devel/flex + sys-devel/bison" +RDEPEND="dev-libs/popt" + +src_compile() { + econf --with-popt || die "econf failed" + emake || die "emake failed" +} + +src_install() { + make DESTDIR="${D}" install || die "install failed" + dodoc README CHANGES +} diff --git a/quickstart/ex3.ebuild b/quickstart/ex3.ebuild new file mode 100644 index 0000000..0d514b7 --- /dev/null +++ b/quickstart/ex3.ebuild @@ -0,0 +1,27 @@ +# Header + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +DESCRIPTION="GNU charset conversion library for libc which doesn't implement it" +SRC_URI="ftp://ftp.gnu.org/pub/gnu/libiconv/${P}.tar.gz" +HOMEPAGE="http://www.gnu.org/software/libiconv/" + +SLOT="0" +LICENSE="LGPL-2.1" +KEYWORDS="~amd64 ~ppc ~sparc ~x86" +IUSE="nls" + +DEPEND="virtual/libc + !sys-libs/glibc" + +src_compile() { + econf $(use_enable nls) || die "econf failed" + emake || die +} + +src_install() { + make DESTDIR="${D}" install || die "install failed" +} + diff --git a/quickstart/ex4.ebuild b/quickstart/ex4.ebuild new file mode 100644 index 0000000..3142640 --- /dev/null +++ b/quickstart/ex4.ebuild @@ -0,0 +1,70 @@ +# Example + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +inherit eutils + +DESCRIPTION="A lightweight email client and newsreader" +HOMEPAGE="http://sylpheed.good-day.net/" +SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2" + +LICENSE="GPL-2" +KEYWORDS="alpha amd64 hppa ia64 ppc ppc64 sparc x86" +SLOT="0" + +IUSE="crypt gnome imlib ipv6 ldap nls pda ssl xface" + +DEPEND="=x11-libs/gtk+-1.2* + nls? ( >=sys-devel/gettext-0.12.1 ) + crypt? ( >=app-crypt/gpgme-0.4.5 ) + gnome? ( media-libs/gdk-pixbuf ) + imlib? ( media-libs/imlib ) + ldap? ( >=net-nds/openldap-2.0.11 ) + pda? ( app-pda/jpilot ) + ssl? ( dev-libs/openssl ) + xface? ( >=media-libs/compface-1.4 )" +RDEPEND="${DEPEND} + app-misc/mime-types + x11-misc/shared-mime-info" + +src_unpack() { + unpack ${A} + cd "${S}" + + epatch "${FILESDIR}"/${PN}-namespace.diff + epatch "${FILESDIR}"/${PN}-procmime.diff +} + +src_compile() { + + econf \ + $(use_enable nls) \ + $(use_enable ssl) \ + $(use_enable crypt gpgme) \ + $(use_enable pda jpilot) \ + $(use_enable ldap) \ + $(use_enable ipv6) \ + $(use_enable imlib) \ + $(use_enable gnome gdk-pixbuf) \ + $(use_enable xface compface) \ + || die + + emake || die +} + +src_install() { + einstall || die "einstall failed" + dodir /usr/share/pixmaps + insinto /usr/share/pixmaps + doins *.png + + if use gnome ; then + dodir /usr/share/gnome/apps/Internet + insinto /usr/share/gnome/apps/Internet + doins sylpheed.desktop + fi + + dodoc [A-Z][A-Z]* ChangeLog* +} diff --git a/quickstart/ex5.ebuild b/quickstart/ex5.ebuild new file mode 100644 index 0000000..c6e3f18 --- /dev/null +++ b/quickstart/ex5.ebuild @@ -0,0 +1,40 @@ +# Header + +# Copyright 1999-2005 Gentoo Foundation +# Distributed under the terms of the GNU General Public License v2 +# $Header: $ + +inherit eutils + +DESCRIPTION="detox safely removes spaces and strange characters from filenames" +HOMEPAGE="http://detox.sourceforge.net/" +SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2" + +LICENSE="BSD" +SLOT="0" +KEYWORDS="~hppa ~mips ~sparc ~x86" +IUSE="" + +DEPEND="dev-libs/popt + sys-devel/flex + sys-devel/bison" +RDEPEND="dev-libs/popt" + +src_unpack() { + unpack ${A} + cd "${S}" + + epatch "${FILESDIR}"/${P}-destdir.patch + epatch "${FILESDIR}"/${P}-parallel_build.patch +} + +src_compile() { + econf --with-popt || die "econf failed" + emake || die "emake failed" +} + +src_install() { + make DESTDIR="${D}" install || die "install failed" + dodoc README CHANGES +} + diff --git a/quickstart/text.rst b/quickstart/text.rst new file mode 100644 index 0000000..02d5854 --- /dev/null +++ b/quickstart/text.rst @@ -0,0 +1,159 @@ +Quickstart Ebuild Guide +======================= + +This page provides a *very* brief introduction to ebuild writing. It does not +attempt to cover many of the details or problems that will be encountered by +developers -- rather, it gives some trivial examples which may be of use when +trying to grasp the basic idea of how ebuilds work. + +For proper coverage of all the ins and outs, see `Ebuild Writing`_. The `General +Concepts`_ chapter will also be of use. + +Note that the examples used here, whilst based upon real tree ebuilds, have had +several parts chopped out, changed and simplified. + +First Ebuild +------------ + +We'll start with an ebuild for the *Exuberant Ctags* utility, a source code +indexing tool. Here's a simplified ``dev-util/ctags/ctags-5.5.4.ebuild`` (you +can see real ebuilds in the main tree). + +.. CODESAMPLE ex1.ebuild + +Basic Format +'''''''''''' + +As you can see, ebuilds are just ``bash`` scripts that are executed within a +special environment. + +At the top of the ebuild is a header block. This is present in all ebuilds. + +Ebuilds are indented using tabs, with each tab representing four places. See +`Ebuild File Format`_. + +Information Variables +''''''''''''''''''''' + +Next, there are a series of variables. These tell portage various things about +the ebuild and package in question. + +The ``DESCRIPTION`` variable is set to a *short* description of the package and +its purpose. + +The ``HOMEPAGE`` is a link to the package's homepage (remember to +include the ``http://`` part). + +The ``LICENSE`` is ``GPL-2`` (the GNU General +Public Licence version 2). + +The ``SRC_URI`` tells portage the address to use for +downloading the source tarball. Here, ``mirror://sourceforge/`` is a special +notation meaning "any of the Sourceforge mirrors". The ``${P}`` is a read-only +variable set by portage which is the package's name and version -- in this case, +it would be ``ctags-5.5.4``. + +The ``SLOT`` variable tells portage which slot this package installs to. If +you've not seen slots before, either just use ``"0"`` or read `Slotting`_. + +The ``KEYWORDS`` variable is set to archs upon which this ebuild has been +tested. We use ``~`` keywords for newly written ebuilds -- packages are not +committed straight to stable, even if they seem to work. See `Keywording`_ for +details. + +Build Functions +''''''''''''''' + +Next, a function named ``src_compile``. Portage will call this function when it +wants to *compile* the package. The ``econf`` function is a wrapper for calling +``./configure``, and ``emake`` is a wrapper for ``make``. In both cases, the +common ``|| die "something went wrong"`` idiom is used -- this is to ensure that +if for some reason an error occurs, portage will stop rather than trying to +continue with the install. + +The ``src_install`` function is called by portage when it wants to *install* the +package. A slight subtlety here -- rather than installing straight to the live +filesystem, we must install to a special location which is given by the ``${D}`` +variable (portage sets this -- see `Install Destinations`_ and `Sandbox`_). +Again, we check for errors. + +.. Note:: The canonical install method is ``make DESTDIR="${D}" install``. This + will work with any properly written standard ``Makefile``. If this gives + sandbox errors, try ``einstall`` instead. If this still fails, see + `src_install`_ for how to do manual installs. + +The ``dodoc`` and ``dohtml`` are helper functions for installing files into the +relevant part of ``/usr/share/doc``. + +Ebuilds can define other functions (see `Ebuild Functions`_). In all cases, +portage provides a reasonable default implementation which quite often does the +'right thing'. There was no need to define a ``src_unpack`` function here, for +example -- this function is used to do any unpacking of tarballs or patching of +source files, but the default implementation does everything we need. + +Ebuild with Dependencies +------------------------ + +In the ctags example, we didn't tell portage about any dependencies. As it +happens, that's ok, because ctags only needs a basic toolchain to compile and +run (see `Implicit System Dependency`_ for why we don't need to depend upon +those explicitly). However, life is rarely that simple. + +Here's ``app-misc/detox/detox-1.1.1.ebuild``: + +.. CODESAMPLE ex2.ebuild + +Again, you can see the ebuild header and the various informational variables. In +``SRC_URI``, ``${PN}`` is used to get the package's name *without* the version +suffix (there are more of these variables -- see `Predefined Read-Only +Variables`_). + +Again, we define ``src_compile`` and ``src_install`` functions. + +The ``DEPEND`` and ``RDEPEND`` variables are how portage determines which +packages are needed to build and run the package. The ``DEPEND`` variable lists +compile-time dependencies, and the ``RDEPEND`` lists runtime dependencies. See +`Dependencies`_ for some more complex examples. + +Ebuild with Patches +------------------- + +Often we need to apply patches. This is done in the ``src_unpack`` function +using the ``epatch`` helper function. To use ``epatch`` one must first tell +portage that the ``eutils`` eclass (an eclass is like a library) is required -- +this is done via ``inherit eutils`` at the top of the ebuild. Here's +``app-misc/detox/detox-1.1.0.ebuild``: + +.. CODESAMPLE ex5.ebuild + +Note the ``${FILESDIR}/${P}-destdir.patch`` -- this refers to +``detox-1.1.0-destdir.patch``, which lives in the ``files/`` subdirectory in the +portage tree. Larger patch files must go on the mirrors rather than in +``files/`` -- see `Basic epatch Usage`_. + +Ebuild with USE Flags +--------------------- + +Now for some ``USE`` flags. Here's ``dev-libs/libiconv/libiconv-1.9.2.ebuild``, +a replacement iconv for ``libc`` implementations which don't have their own. + +.. CODESAMPLE ex3.ebuild + +Note the ``IUSE`` variable. This lists all (non-special) use flags that are used +by the ebuild. This is used for the ``emerge -pv`` output, amongst other things. + +The package's ``./configure`` script takes the usual ``--enable-nls`` or +``--disable-nls`` argument. We use the ``use_enable`` utility function to +generate this automatically (see `Query Functions Reference`_). + +Another more complicated example, this time based upon +``mail-client/sylpheed/sylpheed-1.0.4.ebuild``: + +.. CODESAMPLE ex4.ebuild + +Note the optional dependencies. Some of the ``use_enable`` lines use the +two-argument version -- this is helpful when the USE flag name does not exactly +match the ``./configure`` argument. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/styles/devmanual.css b/styles/devmanual.css new file mode 100644 index 0000000..841b704 --- /dev/null +++ b/styles/devmanual.css @@ -0,0 +1,235 @@ +div.header { + border-bottom: 3px solid #333333; + background-color: #666666; + color: #eeeeee; + margin: 0em 0em 0em 0em; + padding: 0.2em; + font-size: 70%; +} + +div.navtop { + border-bottom: 1px dashed #333333; + text-align: center; +} + +div.navbottom { + border-top: 1px dashed #333333; + text-align: center; + margin-top: 1em; +} + +@media print { + div.header { + display: none; + } +} + +div.header a:link, div.header a:visited, +div.footer a:link, div.footer a:visited { + color: #eeeeee; + font-weight: bold; + text-decoration: none; +} + +div.header a:hover, div.footer a:hover { + color: #eeeeee; + font-weight: bold; + text-decoration: underline; +} + +div.footer { + text-align: center; + border-top: 3px solid #333333; + background-color: #666666; + color: #eeeeee; + margin: 0em 0em 0em 0em; + padding: 0em 0.2em; + font-size: 70%; +} + +@media print { + div.footer { + display: none; + } +} + +div.main { + padding: 1em 40px; + margin: 0em; + background-color: #eeeeee; + color: #333333; +} + +body { + background-color: #666666; + color: #eeeeee; + padding: 0em; + margin: 0em; + font-family: "Verdana", "Arial" "Helvetica", sans-serif; +} + +div.footer * img { + border-width: 0px; +} + +th { + font-weight: bold; + text-align: left; + padding: 0.3em; +} + +th, td { + padding-left: 0.3em; + padding-right: 0.3em; +} + +div.main a:link, div.main a:visited { + color: #000099; + text-decoration: none; +} + +div.main a[href]:hover { + color: #000099; + text-decoration: underline; +} + +div.main pre a:link, div.main pre a:visited { + color: #fff0e0; + text-decoration: none; +} + +div.main pre a[href]:hover { + color: #fff0e0; + text-decoration: underline; +} + +code, tt { + color: #993333; +} + +div.main p, div.main dd { + text-align: justify; +} + +pre { + background-color: #1e1e27; + color: #cfbfad; + padding-top: 3px; + padding-bottom: 3px; + padding-left: 8px; + padding-right: 8px; +} + +div.main h1 { + text-align: center; +} + +div.main h2 { + text-align: left; + border-bottom: 1px dashed #333333; + margin-left: -30px; +} + +div.main h3 { + text-align: left; + margin-left: -30px; +} + +dt { + font-weight: bold; +} + +dd p.first { + margin-top: 0.2em; +} + +dd p.last { + margin-bottom: 0.2em; +} + +div.figure, div.figure p { + text-align: center; + font-weight: bold; +} + +code, pre, tt { + font-family: "Terminus", monospace; +} + +div.warning p.admonition-title, +div.note p.admonition-title, +div.todo p.admonition-title, +div.admonition p.admonition-title, +div.important p.admonition-title { + font-weight: bold; + display: inline; +} + +div.warning p, +div.note p, +div.todo p, +div.admonition p, +div.important p { + display: inline; +} + +div.warning p.admonition-title:after, +div.note p.admonition-title:after, +div.todo p.admonition-title:after, +div.admonition p.admonition-title:after, +div.important p.admonition-title:after { + content: ":"; +} + +div.note, div.warning, +div.important, div.todo, +div.admonition { + padding: 4px; + text-align: justify; +} + +div.note { + background-color: #c9c4ff; +} + +div.warning { + background-color: #ee9999; +} + +div.important { + background-color: #99ee99; +} + +div.todo { + background-color: #cccccc; +} + +div.admonition { + background-color: #ffffff; +} + +blockquote.epigraph p { + font-size: 80%; + font-style: italic; +} + +blockquote.epigraph p.attribution { + font-style: normal; +} + +pre span.Normal { color: #cfbfad; background-color: #1e1e27; } +pre span.Number { color: #506dbd; } +pre span.Special { color: #c080d0; } +pre span.Identifier { color: #ff8bff; } +pre span.Type { color: #ff8bff; } +pre span.PreProc { color: #409090; } +pre span.String { color: #ffcd8b; background-color: #404040; } +pre span.Constant { color: #ffcd8b; } +pre span.lnr { color: #8b8bcd; background-color: #2e2e2e; } +pre span.Comment { color: #cd8b00; } +pre span.Statement { color: #808bed; } +pre span.DiffAdd { color: #40c060; } +pre span.Title { color: #40c060; font-weight: bold; } +pre span.Underlined { font-weight: bold; color: #fff0c0; } + +/* vim: set ts=4 tw=80 et : */ diff --git a/tasks-reference/completion/completion-1.ebuild b/tasks-reference/completion/completion-1.ebuild new file mode 100644 index 0000000..d3fccd4 --- /dev/null +++ b/tasks-reference/completion/completion-1.ebuild @@ -0,0 +1,3 @@ +# Headers. + +complete -o nospace -d cd
\ No newline at end of file diff --git a/tasks-reference/completion/completion-2.ebuild b/tasks-reference/completion/completion-2.ebuild new file mode 100644 index 0000000..57e5cce --- /dev/null +++ b/tasks-reference/completion/completion-2.ebuild @@ -0,0 +1,19 @@ +# Headers. + +_foo() { + local cur prev opts + COMPREPLY=() + cur="${COMP_WORDS[COMP_CWORD]}" + prev="${COMP_WORDS[COMP_CWORD-1]}" + opts="" + + if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] ; then + COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) + return 0 + fi + + case "${prev}" in + # ... + esac +} +complete -F _foo foo diff --git a/tasks-reference/completion/completion-3.ebuild b/tasks-reference/completion/completion-3.ebuild new file mode 100644 index 0000000..d06abfa --- /dev/null +++ b/tasks-reference/completion/completion-3.ebuild @@ -0,0 +1,7 @@ +# Headers. + +case "${prev}" in + -f|--file) + COMPREPLY=( $(compgen -f ? ${cur}) ) + ;; +esac
\ No newline at end of file diff --git a/tasks-reference/completion/completion-4.ebuild b/tasks-reference/completion/completion-4.ebuild new file mode 100644 index 0000000..2f4bb03 --- /dev/null +++ b/tasks-reference/completion/completion-4.ebuild @@ -0,0 +1,39 @@ +# Headers. + +_revdep_rebuild() { + local cur prev opts + COMPREPLY=() + cur="${COMP_WORDS[COMP_CWORD]}" + prev="${COMP_WORDS[COMP_CWORD-1]}" + opts="-X --package-names --soname --soname-regexp -q --quiet" + + if [[ ${cur} == -* || ${COMP_CWORD} -eq 1 ]] || \ + [[ ${prev} == @(-q|--quiet) ]] ; then + COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) ) + return 0 + fi + + case "${prev}" in + -X|--package-names) + _pkgname -I ${cur} + ;; + --soname) + local sonames=$(for x in /lib/*.so?(.)* /usr/lib*/*.so\?(.)* ; do \ + echo ${x##*/} ; \ + done) + COMPREPLY=( $(compgen -W "${sonames}" -- ${cur}) ) + ;; + --soname-regexp) + COMPREPLY=() + ;; + *) + if [[ ${COMP_LINE} == *" "@(-X|--package-names)* ]] ; then + _pkgname -I ${cur} + COMPREPLY=(${COMPREPLY[@]} $(compgen -W "${opts}")) + else + COMPREPLY=($(compgen -W "${opts} -- ${cur}")) + fi + ;; + esac +} +complete -F _revdep_rebuild revdep-rebuild diff --git a/tasks-reference/completion/text.rst b/tasks-reference/completion/text.rst new file mode 100644 index 0000000..2418a06 --- /dev/null +++ b/tasks-reference/completion/text.rst @@ -0,0 +1,154 @@ +Completion Files +================ + +Since v2.05a, ``bash`` has offered intelligent programmable completion. Writing +such completions for your own programs/things you maintain is relatively easy +provided you know bash already. See `bash-completion.eclass Reference`_ for how +to install completion files. + +Completion-Related Internal Bash Variables +------------------------------------------ + +Most of these variables lose their special properties when unset, even if they +are subsequently reset. + +=================== ========================================================== +Variable Purpose +=================== ========================================================== +``COMP_CWORD`` An index into ``${COMP_WORDS}`` of the word containing the + current cursor position. +``COMP_LINE`` The current command line. +``COMP_POINT`` The index of the current cursor position relative to the + beginning of the current command. If the current cursor + position is at the end of the current command, the value + of this variable is equal to ``${#COMP_LINE}``. +``COMP_WORDBREAKS`` The set of characters that the Readline library treats as + word separators when performing word completion. +``COMP_WORDS`` An array variable consisting of the individual words in + the current command line, ``${COMP_LINE}``. +``COMPREPLY`` An array variable from which bash reads the possible + completions generated by a completion function. +=================== ========================================================== + +Completion-Related Bash Builtins +-------------------------------- + +See `bash-1`_ for a full description of these builtins and their options. + +============ ================================================================ +Builtin Usage +============ ================================================================ +``compgen`` ``compgen [-abcdefgjksuv] [-o option] [-A action] [-G globpat] + [-W wordlist] [-P prefix] [-S suffix] [-X filterpat] + [-F function] [-C command] [word]`` + Display the possible completions depending on the options. + Intended to be used from within a shell function generating + possible completions. If the optional WORD argument is supplied, + matches against WORD are generated. +``complete`` ``complete [-abcdefgjksuv] [-pr] [-o option] [-A action] + [-G globpat] [-W wordlist] [-P prefix] [-S suffix] + [-X filterpat] [-F function] [-C command] [name ...]`` + For each NAME, specify how arguments are to be completed. + If the -p option is supplied, or if no options are supplied, + existing completion specifications are printed in a way that + allows them to be reused as input. The -r option removes a + completion specification for each NAME, or, if no NAMEs are + supplied, all completion specifications. +============ ================================================================ + +For extremely simple cases, a simple ``complete`` statement is all that is +needed. For example, minimal ``cd`` completion (minimal as in no support for +``${CDPATH}``) would be as simple as: + +.. CODESAMPLE completion-1.ebuild + +Anatomy of a Completion Function +-------------------------------- + +Nearly all completion functions will start out the same way. For these cases, +the following can be used as a template for creating new completion functions: + +.. CODESAMPLE completion-2.ebuild + +1. The convention for completion function names is usually _NAME, where NAME + is the name of the application/function you are writing the completion + function for. If NAME contains a '-', it should be replaced with a '_'. + Hence bash-completion-config would be _bash_completion_config(). Failing + to do so can cause weird bugs if bash is invoked in POSIX-mode while a + function name containing a '-' is in the environment (POSIX sh does not + allow a '-' in function names). + +3. Resets the ``${COMPREPLY}`` array, as it may be set from a previous + invocation. + +4. Sets the local variable, ``${cur}`` to the current word of the command line. + If the current command line, ``${COMP_LINE}`` is say 'foo --fil', ``${cur}`` + would be equal to '--fil'. If ``${COMP_LINE}`` is equal to 'foo --file ' + (note the space at the end), ``${cur}`` is null. + +5. Sets the local variable, ``${prev}`` to the previous word of the command + line. ``${prev}`` is the word before ``${cur}``. + +6. Sets the local variable, ``${opts}``. In a real completion function, this + variable would be set to all the options that ``foo`` recognizes. + +8. Tests whether or not the current word is equivalent to -* (an option) or if + we're completing on the first word (ie. ``${COMP_CWORD}`` == 1). + +9. If the test returns true, show the available options, ``${opts}``. The -W + option to ``compgen`` tells bash to complete on the word list (string or + something that evaluates to a string). In the majority of cases, you'll + pass ``'-- ${cur}'`` to ``compgen`` telling it to only return those + completions that match ``${cur}``. + +13. Most of the time, you'll want to perform a certain action if ``${prev}`` is + equal to a certain option. For example, if ``foo`` has a --file option + (and -f for short) that takes any kind file, you could do: + + .. CODESAMPLE completion-3.ebuild + +.. case "${prev}" in + -f|--file) + COMPREPLY=( $(compgen -f -- ${cur}) ) + ;; + esac .. + +17. Tells bash to use the ``_foo`` function to generate any completions for + the ``foo`` application/function. + + +Real-World Example +------------------ + +For this document, I will take you through a real-world example and write a +real completion function for ``revdep-rebuild`` (might even be available in +``gentoo-bashcomp`` by the time you read this :]). + +.. CODESAMPLE completion-4.ebuild + +Lines 1-12 are pretty much the same as in the previous section. + +15. If ``${prev}`` is equal to -X|--package-names, call _pkgname (a function + defined by ``gentoo-bashcomp`` that completes on package names - it sets + ``${COMPREPLY}``, so we don't worry about that here). + +18. If ``${prev}`` is equal to --soname, generate a list of all shared libs + in /lib and /usr/lib*. Pass that list to ``compgen`` to generate a list + of possible completions that match ``${cur}``. + +24. Obviously we cannot complete on any regexp's so if ``${prev}`` is equal + to --soname-regexp, do nothing. + +27. For anything else (any options not specified in the case statement above + OR any argument to one of the options specified in the case statement) + perform the tests. Since --package-names can take multiple package + names, we want to continue to complete on package names until another + recognized option is encountered (ie. is ``${prev}``). + +30. Since _pkgname sets ``${COMPREPLY}`` and we want to add to that list, + we have to use the COMPREPLY=(${COMPREPLY[@] ... ) construct. + +37. Tell bash to use _revdep_rebuild to generate all possible completions + for revdep-rebuild. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/tasks-reference/environment/text.rst b/tasks-reference/environment/text.rst new file mode 100644 index 0000000..6aeb72c --- /dev/null +++ b/tasks-reference/environment/text.rst @@ -0,0 +1,18 @@ +Environment Files +================= + +Some packages need to globally set an environment variable for all users. The +canonical way of doing this is via ``/etc/env.d``. All files in this directory +are sourced when generating user environment settings. + +This directory should **only** be used for setting environment variables. + +To install a file into this directory, use ``doenvd`` or ``newenvd`` (see +`Install Functions Reference`_). The format of the file should be a series of +lines in the form ``VARIABLE="the value"``. + +There is further discussion in the `main handbook Environment Variables section +<http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=5>`__. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tasks-reference/init-scripts/text.rst b/tasks-reference/init-scripts/text.rst new file mode 100644 index 0000000..0c2199d --- /dev/null +++ b/tasks-reference/init-scripts/text.rst @@ -0,0 +1,15 @@ +Init Scripts +============ + +Init scripts should be installed into ``/etc/init.d`` using the ``doinitd`` or +``newinitd`` functions (see `Install Functions Reference`_). Any configuration +(commandline parameters or environment variables) for these scripts should be +handled via entries in ``/etc/conf.d`` with the same filename -- ``doconfd`` or +``newconfd`` can be used to install these. + +An overview of the Gentoo init system and how to write init scripts is available +in the `main handbook Writing Init Scripts section +<http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=4#doc_chap4>`__. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tasks-reference/pam/text.rst b/tasks-reference/pam/text.rst new file mode 100644 index 0000000..1f444dd --- /dev/null +++ b/tasks-reference/pam/text.rst @@ -0,0 +1,170 @@ +Working with PAM +================ + +PAM (Pluggable Authentication Modules) is a mechanism which allows different +applications to authenticate using various specified parameters, using for +example a passwd/shadow file, a Kerberos server, an LDAP server or an a NT +Domain server (using Samba). + +With PAM, a program just needs to require authentication for a given login class +(defined in a ``pam.d`` file), and PAM framework will take care of calling the +modules which will provide authentication. + +There are different PAM implementations. Gentoo Linux, by default, uses the +Linux-PAM implementation which is installed via ``sys-libs/pam``; FreeBSD and +NetBSD (and hence Gentoo/FreeBSD) use OpenPAM, which is a minimal version. The +different implementations can provide different authentication modules, and can +differ in some details of the configuration. + +Structure of a ``pamd`` File +---------------------------- + +But let's see the structure of a ``pamd`` file. First of all, the ``pamd ``files +are placed in ``/etc/pam.d``, and they are structured as one statement per line. +The statement is composed of 3 or 4 tokens: + +* The first token specifies the type of service for which the statement is done. + There are four types: + + + *account*, which checks for validity of the user account. + + *auth*, which verifies that the user is who is claim to be, using passwords + or other ways such as biometric and smart-card devices. + + *password*, which takes care of changing users' password. + + *session*, which covers tasks such as checks for the user validity or + mount/umount of home directories, executed both before starting and after + closing the user session. + +* The second token is the control that tells PAM how to behave with failures and success of the authentication for the module specified: + + + *requisite*, a failure results in the termination of the process. + + *required*, a failure will lead in a failure for the service, but before + this, all the other modules are being executed. + + *sufficient*, a success in this module leads to a success in authentication + if no *required* module failed before of it. + + *optional*, in which case the failure or the success are ignored if this is + not the only module present, in which case a success or a failure of it + makes the authentication succeed or fail. + +* The third token is the module to execute for that type of service; PAM modules + are extensible and, as the name says, pluggable. The result is that there are + a small number of default modules and some external optional modules which can + be built against PAM implementation to define additional authentication + methods. Some documentation states that we need to specify the full path of + the module, but this creates problems because not all the systems install the + modules in the same place: Linux-PAM on Gentoo is generally set up to load + them from ``/lib/security``, but for example on AMD64 this become + ``/lib64/security``, and on OpenPAM they are just in ``/usr/lib(64)``. The + result is that providing the full path will lead to non-working ``pamd`` + files, and the right way to handle this is just states the module name -- the + PAM implementation will take care of finding the module. + +* The last token, which can consist of multiple items, describe the parameters + passed to the module. These are module-dependent. + +As the number and the type of modules shipped with the implementation depends on +the implementations themselves (Linux-PAM provides a full working set of +modules, OpenPAM doesn't provide modules at all, and it's the operating system +which provides them, as FreeBSD or NetBSD do), there are just a few modules +which can be used directly in ``pamd`` files without the risk of providing a +non-working configuration file: + +* ``pam_deny.so``, ``pam_permit.so`` -- they just report a failure or a success +* ``pam_rootok.so`` reports success if the user is root, else a failure +* ``pam_nologin.so`` checks for presence of /etc/nologin file with a reason for + blocking user logins -- it's used for example when it's better to avoid users + logging in on a compromised system +* ``pam_securetty.so`` checks that the login is done in a tty which is + considered secure by a configuration file (depends on the implementation) +* ``pam_unix.so`` is the base module for Unix systems, it just checks the + user/password pair with ``/etc/passwd`` and ``/etc/shadow``. + +There are also other modules which can be used for more complex authentication +against a database (mysql or postgresql), against an LDAP directory or against +an NT domain (using samba). This is useful on thin or fat clients where the +users have an unique login for all the machines. Another place where this is +useful is a cluster of servers which needs to authenticate against a single +source for some services, such as mail and ftp servers. + +But for desktop systems, all the different services, such as mail servers, ftp +servers, ssh and so on, just need to authenticate in the same way the users logs +in to the system. + +To achieve this, RedHat developed for Linux-PAM (which hadn't had a way to rely +on another authentication scheme) a ``pam_stack.so`` module which accepted as +parameter ``"login=<login service to use>"``, telling PAM to execute the auth +stack for the service stated. + +Unfortunately that module relied upon internal data structures of Linux-PAM and +assumptions which aren't valid for other PAM implementations, so it is +completely non-portable. It is not used in all the implementations of Linux-PAM +(see for example MacOS X, which uses Linux-PAM but doesn't provide +``pam_stack.so``), and so it's not present on all Linux distributions. + +A solution came when AltLinux developers added a new instruction for the control +token: *include*. That control token can be used on Linux-PAM 0.78 and on +OpenPAM to do the same as a ``required pam_stack.so``, replacing the module name +with the name of the login class to mimic. + +In this way, instead of loading a module which in turn reloads pam, the option +is parsed directly by the PAM implementation which loads the other login class +and takes care of executing it, and the same syntax is valid on both Linux-PAM +and OpenPAM systems. + +New packages (and new versions of old packages) should then use the ``include`` +directive instead of ``pam_stack.so`` module, but to do that they need to depend +on a later version of ``sys-libs/pam`` or on ``sys-libs/openpam`` (note: openpam +is for now just on G/FreeBSD's project overlay) -- to resolve this, +``virtual/pam`` is set up to add the right dependency for the use of the include +directive. + +Installing ``pamd`` Files +------------------------- + +The right place for ``pamd`` files is ``/etc/pam.d``, but installing them by +hand checking for ``pam`` USE flag is tricky and doesn't follow the same path as +initd and confd files, so the solution is to use the ``pam`` eclass. + +In the ``pam`` eclass there are functions which provide installation facilities +for ``pamd`` files (``dopamd`` and ``newpamd``, whose usage is the same as +similar ``do*`` and ``new*`` functions) and the ``/etc/security`` files +(``dopamsecurity`` and ``newpamsecurity``, which need the first argument to be +the subdirectory of ``/etc/security`` in which the files are to be installed). +Those groups of functions already takes care of verifying whether the ``pam`` +USE flag is made optional for the package -- if this is the case, and the flag +is disabled, the ``pamd`` files are just skipped. + +Many ``pamd`` files just uses one or more auth types from ``system-auth`` login class, +which is the base one which provides login facilities for most services on +common desktop systems. Instead of adding a ``pamd`` file in ``${FILESDIR}`` +for this, one can use the ``pamd_mimic_system`` function. This function takes a series +of parameters -- the first one is the name of the login class (the name of the +``pamd`` file in /etc/pam.d); the others are the auth types for which system-auth +needs to be used. + +For example, a call like: :: + + pamd_mimic_system foo auth password + +installs an ``/etc/pam.d/foo`` file which contains: :: + + auth include system-auth + password include system-auth + +which just uses ``system-auth`` login class. + +Installing PAM Modules +---------------------- + +As PAM modules are looked for in different directories on different +implementations, which also depends on the libdir's name for ARCHs with more +than one ABI, usually is not possible to trust the default directory stated by +the module (always if the module state a default directory). The solution for +this is also in ``pam`` eclass. The function ``getpam_mod_dir`` returns the +correct directory to use for the current implementation/arch. + +When the PAM mdoule doesn't provide a way to install the package by itself, such +as a ``Makefile`` or an installation script, there are also the ``dopammod`` and +``newpammod`` functions which takes care of install the module in the right +directory. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/tasks-reference/perl-modules/text.rst b/tasks-reference/perl-modules/text.rst new file mode 100644 index 0000000..d30bf9a --- /dev/null +++ b/tasks-reference/perl-modules/text.rst @@ -0,0 +1,11 @@ +Perl Modules +============ + +This section covers where and how Perl modules should be installed. This is for +Perl applications which use their own ``.pm`` files, **not** for CPAN things. + +.. Todo:: write me. see thread on -dev. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/tasks-reference/text.rst b/tasks-reference/text.rst new file mode 100644 index 0000000..4d623e4 --- /dev/null +++ b/tasks-reference/text.rst @@ -0,0 +1,10 @@ +Tasks Reference +=============== + +This section covers various common tasks which may are used by many different +ebuilds. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/text.rst b/text.rst new file mode 100644 index 0000000..990353e --- /dev/null +++ b/text.rst @@ -0,0 +1,69 @@ +Introduction +============ + +.. epigraph:: + A policy is a restrictive document to prevent a recurrence of a single + incident, in which that incident is never mentioned. + + -- Kaufman's Law + +This document is an ongoing work in progress. It contains gaps, +inaccuracies, omissions, typos and the occasional outright lie. The +intent is to make an handbook giving developers and users correct, +detailed, up to date technical content. + +Contributions are encouraged. See the `Contributing to This Document`_ section +for how to get started. Thanks for Ciaran for permitting me to continue this +and sending me the RST source and needed scripts. + +Authors +------- + +Ciaran McCreesh <ciaranm@gentoo.org> + Main content + +Tim Yamin <plasmaroo@gentoo.org> + Editing + +Grant Goodyear <g2boojum@gentoo.org> + `Here Documents`_, `Distutils`_ + +Aaron Walker <ka0ttic@gentoo.org> + `Completion Files`_, `subversion.eclass Reference`_ + +Robert Coie <rac@gentoo.org> + `Configuring xemacs for UTF-8`_ + +Tom Martin <slarti@gentoo.org> + `Configuring emacs for UTF-8`_, `Subversion Sources`_, `Conflicting USE + Flags`_ + +Paul Varner <fuzzyray@gentoo.org> + `RPM Sources`_ + +Ilya Volynets-Evenbakh <iluxa@gentoo.org> + `MIPS ABIs`_ + +Diego Pettenò <flameeyes@gentoo.org> + `Working with PAM`_, `aclocal and m4 Files`_ + +Fernando J. Pereda <ferdy@gentoo.org> + `Arch Specific Notes -- Alpha`_ + +Simon Stelling <blubb@gentoo.org> + `Arch Specific Notes -- AMD64/EM64T`_ + +Alin Dobre <alin@gentoo.org> + `echo -- Print strings`_ + +Contents +-------- + +.. CHILDLIST + +Full Contents +------------- + +.. FULLCHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/todolist/text.rst b/todolist/text.rst new file mode 100644 index 0000000..69fc905 --- /dev/null +++ b/todolist/text.rst @@ -0,0 +1,10 @@ +Todo List +========= + +This todo list is automatically generated from the ``.. Todo::`` directives in +other documents. + +.. TODOLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tools-reference/bash/bash-1.ebuild b/tools-reference/bash/bash-1.ebuild new file mode 100644 index 0000000..a52202d --- /dev/null +++ b/tools-reference/bash/bash-1.ebuild @@ -0,0 +1,5 @@ +# Header. + +if something ; then + do_stuff +fi diff --git a/tools-reference/bash/bash-10.ebuild b/tools-reference/bash/bash-10.ebuild new file mode 100644 index 0000000..39b7db4 --- /dev/null +++ b/tools-reference/bash/bash-10.ebuild @@ -0,0 +1,5 @@ +# Header. + +while read myline ; do + einfo "It says ${myline}" +done < some_file diff --git a/tools-reference/bash/bash-11.ebuild b/tools-reference/bash/bash-11.ebuild new file mode 100644 index 0000000..7c3e977 --- /dev/null +++ b/tools-reference/bash/bash-11.ebuild @@ -0,0 +1,5 @@ +# Header. + +somevar="Hello World" +echo "${somevar} is ${#somevar} characters long" + diff --git a/tools-reference/bash/bash-12.ebuild b/tools-reference/bash/bash-12.ebuild new file mode 100644 index 0000000..5e65daf --- /dev/null +++ b/tools-reference/bash/bash-12.ebuild @@ -0,0 +1,3 @@ +# Header. + +myconf="$(use_enable acl ) $(use_enable nls ) --with-tlib=ncurses" diff --git a/tools-reference/bash/bash-2.ebuild b/tools-reference/bash/bash-2.ebuild new file mode 100644 index 0000000..85876e4 --- /dev/null +++ b/tools-reference/bash/bash-2.ebuild @@ -0,0 +1,11 @@ +# Header. + +if something ; then + do_stuff +elif something_else ; then + do_other_stuff +elif full_moon ; then + howl +else + turn_into_a_newt +fi diff --git a/tools-reference/bash/bash-3.ebuild b/tools-reference/bash/bash-3.ebuild new file mode 100644 index 0000000..5056e55 --- /dev/null +++ b/tools-reference/bash/bash-3.ebuild @@ -0,0 +1,8 @@ +# Header. + +if some_stuff ; then + # A statement is required here. a blank or a comment + # isn't enough! +else + einfo "Not some stuff" +fi diff --git a/tools-reference/bash/bash-4.ebuild b/tools-reference/bash/bash-4.ebuild new file mode 100644 index 0000000..13edf37 --- /dev/null +++ b/tools-reference/bash/bash-4.ebuild @@ -0,0 +1,8 @@ +# Header. + +if some_stuff ; then + # Do nothing + : +else + einfo "Not some stuff" +fi diff --git a/tools-reference/bash/bash-5.ebuild b/tools-reference/bash/bash-5.ebuild new file mode 100644 index 0000000..c18fa4f --- /dev/null +++ b/tools-reference/bash/bash-5.ebuild @@ -0,0 +1,14 @@ +# is $foo zero length? +if [[ -z "${foo}" ]] ; then + die "Please set foo" +fi + +# is $foo equal to "moo"? +if [[ "${foo}" == "moo" ]] ; then + einfo "Hello Larry" +fi + +# does "${ROOT}/etc/deleteme" exist? +if [[ -f "${ROOT}/etc/deleteme" ]] ; then + einfo "Please delete ${ROOT}/etc/readme manually!" +fi diff --git a/tools-reference/bash/bash-6.ebuild b/tools-reference/bash/bash-6.ebuild new file mode 100644 index 0000000..a4a10cf --- /dev/null +++ b/tools-reference/bash/bash-6.ebuild @@ -0,0 +1,6 @@ +# Header. + +bash$ [ -n $foo ] && [ -z $foo ] && echo "huh?" +huh? +bash$ [[ -n $foo ]] && [[ -z $foo ]] && echo "huh"? +bash$ diff --git a/tools-reference/bash/bash-7.ebuild b/tools-reference/bash/bash-7.ebuild new file mode 100644 index 0000000..5f1f568 --- /dev/null +++ b/tools-reference/bash/bash-7.ebuild @@ -0,0 +1,5 @@ +# Header. + +for myvar in "the first" "the second" "and the third" ; do + einfo "This is ${myvar}" +done diff --git a/tools-reference/bash/bash-8.ebuild b/tools-reference/bash/bash-8.ebuild new file mode 100644 index 0000000..3639a28 --- /dev/null +++ b/tools-reference/bash/bash-8.ebuild @@ -0,0 +1,6 @@ +# Header. + +for (( i = 1 ; i <= 10 ; i++ )) ; do + einfo "i is ${i}" +done + diff --git a/tools-reference/bash/bash-9.ebuild b/tools-reference/bash/bash-9.ebuild new file mode 100644 index 0000000..a800a5a --- /dev/null +++ b/tools-reference/bash/bash-9.ebuild @@ -0,0 +1,5 @@ +# Header. + +while hungry ; do + eat_cookies +done diff --git a/tools-reference/bash/text.rst b/tools-reference/bash/text.rst new file mode 100644 index 0000000..f449af1 --- /dev/null +++ b/tools-reference/bash/text.rst @@ -0,0 +1,372 @@ +bash -- Standard Shell +====================== + +A thorough understanding of ``bash`` programming is vital when working with +ebuilds. + +Bash Conditionals +----------------- + +Basic Selection +''''''''''''''' + +The basic conditional operator is the ``if`` statement: + +.. CODESAMPLE bash-1.ebuild + +Multiple Selection +'''''''''''''''''' + +Multiple pronged selection can be done using ``else`` and ``elif``: + +.. CODESAMPLE bash-2.ebuild + +.. Warning:: You **must** specify at least one statement inside each block. The + following will **not** work: + +.. CODESAMPLE bash-3.ebuild + +If you really don't want to restructure the block, you can use a single colon +(``:``) on its own as a null statement. + +.. CODESAMPLE bash-4.ebuild + +Selection Tests +''''''''''''''' + +To do comparisons or file attribute tests, ``[ ]`` or ``[[ ]]`` blocks are +needed. + +.. CODESAMPLE bash-5.ebuild + +Single versus Double Brackets in ``bash`` +''''''''''''''''''''''''''''''''''''''''' + +.. Important:: The ``[[ ]]`` form is generally safer than ``[ ]`` and should + be used in all new code. + +This is because ``[[ ]]`` is a bash syntax construct, whereas ``[ ]`` is a +program which happens to be implemented as an internal -- as such, cleaner +syntax is possible with the former. For a simple illustration, consider: + +.. CODESAMPLE bash-6.ebuild + +String Comparison in ``bash`` +'''''''''''''''''''''''''''''' + +The general form of a string comparison is ``string1 operator string2``. The +following are available: + +==================== ======================================================= +Operator Purpose +==================== ======================================================= +``==`` (also ``=``) String equality +``!=`` String inequality +``<`` String lexiographic comparison (before) +``>`` String lexiographic comparison (after) +``=~`` String regular expression match (**bash 3 only**, not + currently allowed in ebuilds) +==================== ======================================================= + +String Tests in ``bash`` +'''''''''''''''''''''''' + +The general form of string tests is ``-operator "string"``. The following are +available: + +==================== ========================================= +Operator Purpose +==================== ========================================= +``-z "string"`` String has zero length +``-n "string"`` String has non-zero length +==================== ========================================= + +.. Note:: To check whether a variable is set and not blank, use ``-n "${BLAH}"`` + rather than ``-n $BLAH``. The latter will cause problems in some situations if + the variable is unset. + +Integer Comparison in ``bash`` +'''''''''''''''''''''''''''''' + +The general form of integer comparisons is ``int1 -operator int2``. The +following are available: + +==================== ========================================= +Operator Purpose +==================== ========================================= +``-eq`` Integer equality +``-ne`` Integer inequality +``-lt`` Integer less than +``-le`` Integer less than or equal to +``-gt`` Integer greater than +``-ge`` Integer greater than or equal to +==================== ========================================= + +File Tests in ``bash`` +'''''''''''''''''''''' + +The general form of a file test is ``-operator "filename"``. The following are +available (lifted from `bash-1`_): + +==================== ========================================= +Operator Purpose +==================== ========================================= +``-a file`` Exists (use ``-e`` instead) +``-b file`` Exists and is a block special file +``-c file`` Exists and is a character special file +``-d file`` Exists and is a directory +``-e file`` Exists +``-f file`` Exists and is a regular file +``-g file`` Exists and is set-group-id +``-h file`` Exists and is a symbolic link +``-k file`` Exists and its sticky bit is set +``-p file`` Exists and is a named pipe (FIFO) +``-r file`` Exists and is readable +``-s file`` Exists and has a size greater than zero +``-t fd`` Descriptor fd is open and refers to a terminal +``-u file`` Exists and its set-user-id bit is set +``-w file`` Exists and is writable +``-x file`` Exists and is executable +``-O file`` Exists and is owned by the effective user id +``-G file`` Exists and is owned by the effective group id +``-L file`` Exists and is a symbolic link +``-S file`` Exists and is a socket +``-N file`` Exists and has been modified since it was last read +==================== ========================================= + +File Comparison in ``bash`` +''''''''''''''''''''''''''' + +The general form of a file comparison is ``"file1" -operator "file2"``. The +following are available (lifted from `bash-1`_): + +==================== ===================================================== +Operator Purpose +==================== ===================================================== +``file1 -nt file2`` file1 is newer (according to modification date) than + file2, or if file1 exists and file2 does not. +``file1 -ot file2`` file1 is older than file2, or if file2 exists and + file1 does not. +``file1 -ef file2`` file1 and file2 refer to the same device and inode + numbers. +==================== ===================================================== + +Boolean Algebra in ``bash`` +''''''''''''''''''''''''''' + +There are constructs available for boolean algebra ('and', 'or' and 'not'). +These are used *outside* of the ``[[ ]]`` blocks. For operator precedence, use +``( )``. + +============================= ================================== +Construct Effect +============================= ================================== +``first || second`` first *or* second (short circuit) +``first && second`` first *and* second (short circuit) +``! condition`` *not* condition +============================= ================================== + + +.. Note:: These will also sometimes work *inside* ``[[ ]]`` constructs, and using + ``!`` before a test is fairly common. ``[[ ! -foo ]] && bar`` is fine. However, + there are catches -- ``[[ -f foo && bar ]]`` will **not** work properly, since + commands cannot be run inside ``[[ ]]`` blocks. + +Inside ``[ ]`` blocks, several ``-test`` style boolean operators are available. +These should be avoided in favour of ``[[ ]]`` and the above operators. + +Bash Iterative Structures +------------------------- + +There are a few simple iterative structures available from within ``bash``. The +most useful of these is a ``for`` loop. This can be used to perform the same +task upon multiple items. + +.. CODESAMPLE bash-7.ebuild + +There is a second form of the ``for`` loop which can be used for repeating an +event a given number of times. + +.. CODESAMPLE bash-8.ebuild + +There is also a ``while`` loop, although this is usually not useful within +ebuilds. + +.. CODESAMPLE bash-9.ebuild + +This is most commonly used to iterate over lines in a file: + +.. CODESAMPLE bash-10.ebuild + +See `die and Subshells`_ for an explanation of why ``while read < file`` should +be used over ``cat file | while read``. + +Bash Variable Manipulation +-------------------------- + +There are a number of special ``${}`` constructs in ``bash`` which either +manipulate or return information based upon variables. These can be used instead +of expensive (or illegal, if we're in global scope) external calls to ``sed`` +and friends. + +``bash`` String Length +'''''''''''''''''''''' + +The ``${#somevar}`` construct can be used to obtain the length of a string +variable. + +.. CODESAMPLE bash-11.ebuild + +``bash`` Variable Default Values +'''''''''''''''''''''''''''''''' + +There are a number of ways of using a default value if a variable is unset or +zero length. The ``${var:-value}`` construct expands to the value of ``${var}`` +if it is set and not null, or ``value`` otherwise. The ``${var:value}`` +construct is similar, but checks only that the variable is set. + +The ``${var:=value}`` and ``${var=value}`` forms will also assign ``value`` to +``var`` if ``var`` is unset (and not null for the ``:=`` form). + +The ``${var:?message}`` form will display ``message`` to stderr and then exit if +``var`` is unset or null. This should generally not be used within ebuilds as it +does not use the ``die`` mechanism. There is a ``${var?message}`` form too. + +The ``${var:+value}`` form expands to ``value`` if ``var`` is set and not null, +or a blank string otherwise. There is a ``${var+value}`` form. + +``bash`` Substring Extraction +''''''''''''''''''''''''''''' + +The ``${var:offset}`` and ``${var:offset:length}`` constructs can be used to +obtain a substring. Strings are zero-indexed. Both ``offset`` and ``length`` are +arithmetic expressions. + +The first form with a positive offset returns a substring starting with the +character at ``offset`` and continuing to the end of a string. If the offset is +negative, the offset is taken relative to the *end* of the string. + +.. Note:: For reasons which will not be discussed here, any negative value must be + an *expression* which results in a negative value, rather than simply a negative + value. The best way to handle this is to use ``${var:0-1}``. ``${var:-1}`` will + **not** work. + +The second form returns the first ``length`` characters of the value of +``${var}`` starting at ``offset``. If ``offset`` is negative, the offset is +taken from the *end* of the string. The ``length`` parameter *must not* be less +than zero. Again, negative ``offset`` values must be given as an expression. + +``bash`` Command Substitution +''''''''''''''''''''''''''''' + +The ``$(command )`` construct can be used to run a command and capture the +output (``stdout``) as a string. + +.. Note:: The ```command``` construct also does this, but should be avoided in + favour of ``$(command )`` for clarity, ease of reading and nesting purposes. + +.. CODESAMPLE bash-12.ebuild + + +``bash`` String Replacements +'''''''''''''''''''''''''''' + +There are three basic string replacement forms available: ``${var#pattern}``, +``${var%pattern}`` and ``${var/pattern/replacement}``. The first two are used +for deleting content from the start and end of a string respectively. The third +is used to replace a match with different content. + +The ``${var#pattern}`` form will return ``var`` with the shortest match of +``pattern`` at the start of the value of ``var`` deleted. If no match can be +made, the value of ``var`` is given. To delete the *longest* match at the start, +use ``${var##pattern}`` instead. + +The ``${var%pattern}`` and ``${var%%pattern}`` forms are similar, but delete the +shortest and longest matches at the *end* of ``var`` respectively. + +.. Note:: The terms *greedy* and *non-greedy* are sometimes used here (``%`` and + ``#`` being the non-greedy forms). This is arguably incorrect, but the terms + are fairly close. + +The ``${var/pattern/replacement}`` construct expands to the value of ``var`` +with the first match of ``pattern`` replaced with ``replacement``. To replace +*all* matches, ``${var//pattern/replacement}`` can be used. + +.. Note:: `bash-1`_ incorrectly describes what will be matched. Of all the possible + leftmost matches, the longest will be taken. Yes, really, the longest, even if + it involves favouring later groups or later branches. This is **not** like + ``perl`` or ``sed``. See `IEEE1003.1-2004-9.1`_ for details. + +To match only if ``pattern`` occurs at the start of the value of ``var``, the +pattern should begin with a ``#`` character. To match only at the end, the +pattern should begin with a ``%``. + +If ``replacement`` is null, matches are deleted and the ``/`` following +``pattern`` may be omitted. + +The ``pattern`` may contain a number of special metacharacters for pattern +matching. + +.. Todo:: tables of bash metachars + +If the ``extglob`` shell option is enabled, a number of additional constructs +are available. These can be *extremely* useful sometimes. + +.. Todo:: table of extra bash goodies + +``bash`` Arithmetic Expansion +''''''''''''''''''''''''''''' + +The ``$(( expression ))`` construct can be used for integer arithmetic +evaluation. ``expression`` is a C-like arithmetic expression. The following +operators are supported (the table is in order of precedence, highest first): + ++-----------------------+-------------------------------------------------------+ +| Operators | Effect | ++=======================+=======================================================+ +| ``var++``, ``var--`` | Variable post-increment, post-decrement | ++-----------------------+-------------------------------------------------------+ +| ``++var``, ``--var`` | Variable pre-increment, pre-decrement | ++-----------------------+-------------------------------------------------------+ +| ``-``, ``+`` | Unary minus and plus | ++-----------------------+-------------------------------------------------------+ +| ``!``, ``~`` | Logical negation, bitwise negation | ++-----------------------+-------------------------------------------------------+ +| ``**`` | Exponentiation | ++-----------------------+-------------------------------------------------------+ +| ``*``, ``/``, ``%`` | Multiplication, division, remainder | ++-----------------------+-------------------------------------------------------+ +| ``+``, ``-`` | Addition, subtraction | ++-----------------------+-------------------------------------------------------+ +| ``<<``, ``>>`` | Left, right bitwise shifts | ++-----------------------+-------------------------------------------------------+ +| ``<=``, ``>=``, | Comparison: less than or equal to, greater than or | +| ``<``, ``>`` | equal to, strictly less than, strictly greater than | ++-----------------------+-------------------------------------------------------+ +| ``==``, ``!=`` | Equality, inequality | ++-----------------------+-------------------------------------------------------+ +| ``&`` | Bitwise AND | ++-----------------------+-------------------------------------------------------+ +| ``^`` | Bitwise exclusive OR | ++-----------------------+-------------------------------------------------------+ +| ``|`` | Bitwise OR | ++-----------------------+-------------------------------------------------------+ +| ``&&`` | Logical AND | ++-----------------------+-------------------------------------------------------+ +| ``||`` | Logical OR | ++-----------------------+-------------------------------------------------------+ +| ``expr ? expr : expr``| Conditional operator | ++-----------------------+-------------------------------------------------------+ +| ``=``, ``*=``, ``/=``,| Assignment | +| ``%=``, ``+=``, | | +| ``-=``, ``<<=``, | | +| ``>>=``, ``&=``, | | +| ``^=``, ``|=`` | | ++-----------------------+-------------------------------------------------------+ +| ``expr1 , expr2`` | Multiple statements | ++-----------------------+-------------------------------------------------------+ + + +.. Note:: There is no ``**=`` assignment operator. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/tools-reference/cat/code-sample-1.ebuild b/tools-reference/cat/code-sample-1.ebuild new file mode 100644 index 0000000..cd9980b --- /dev/null +++ b/tools-reference/cat/code-sample-1.ebuild @@ -0,0 +1,10 @@ +# Header. + +src_install() { + # ... + cat <<- EOF > ${D}/etc/mail/trusted-users + # trusted-users - users that can send mail as others without a warning + # apache, mailman, majordomo, uucp are good candidates + EOF + # ... +} diff --git a/tools-reference/cat/text.rst b/tools-reference/cat/text.rst new file mode 100644 index 0000000..4ea2979 --- /dev/null +++ b/tools-reference/cat/text.rst @@ -0,0 +1,48 @@ +cat -- File Concatenation +========================= + +The ``cat`` command can be used to concatenate the contents of two or more +files. The usage is ``cat firstfile secondfile ...``. + +Abuse of ``cat`` +---------------- + +If you find yourself about to use ``cat`` in an ebuild, stop and reconsider. It +is almost always unnecessary. + +All usages in the form ``cat somefile | somecommand`` are silly and should be +eschewed. The form ``somecommand < somefile`` does the same thing, and doesn't +involve an extra fork and a pipe. With many standard utilities the ``somecommand +somefile`` form will work as well. + +Using ``foo=$(cat somefile)`` to place the contents of a file into the +variable ``foo`` is also unnecessary. The command ``foo=$(<somefile)`` works +just as well and doesn't require a fork. Similarly, ``cat file | xargs cmd`` and +``xargs cmd < file`` can be replaced by ``cmd $(<file)``. + +Finally, ``cat foo > bar``, where ``foo`` is a single file, can usually be +replaced by ``cp -f foo bar``. + +Here Documents +-------------- + +On the other hand, ``cat`` is exceptionally useful for so-called "here" +documents, such as the following example from ``sendmail-8.13.3 ebuild`` + +.. CODESAMPLE code-sample-1.ebuild + +In this example ``cat`` is used inside ``src_install`` to create the +``${D}/etc/mail/trusted-users`` file. Specifically, the new file will comprise +the lines between the ``cat`` line and the line with ``EOF`` in the ebuild. + +The funny hyphen in ``<<-`` is a >=bash-2.05 syntax that tells +``cat`` to strip leading tabs (please note that when you want to copy +the example, you have to replace the leading spaces with tabs), so +that, as Azarah puts it, "we won't have the ebuilds looking from space +effect". For such small files as the example above, a set of here +documents is more elegant, and easier to maintain, than the equivalent +bunch of files floating about in ``${FILESDIR}`` would be. If for some +reason you need to preserve leading whitespace, then simply use ``<<`` +instead of ``<<-`` to get the desired effect. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/tools-reference/cut/cut-1.ebuild b/tools-reference/cut/cut-1.ebuild new file mode 100644 index 0000000..0124dde --- /dev/null +++ b/tools-reference/cut/cut-1.ebuild @@ -0,0 +1,3 @@ +# Header. + +cut -s -d',' -f2,4-5 input.txt > output.txt diff --git a/tools-reference/cut/cut-2.ebuild b/tools-reference/cut/cut-2.ebuild new file mode 100644 index 0000000..1bc4e1f --- /dev/null +++ b/tools-reference/cut/cut-2.ebuild @@ -0,0 +1,3 @@ +# Header. + +do_stuff | cut -c2- diff --git a/tools-reference/cut/text.rst b/tools-reference/cut/text.rst new file mode 100644 index 0000000..0d006db --- /dev/null +++ b/tools-reference/cut/text.rst @@ -0,0 +1,37 @@ +cut -- Column Extraction +======================== + +The ``cut`` tool can be used to extract specific columns from files which are +delimited by a particular character or by column numbers. It can be passed +filenames on the commandline; if none are specified, it reads from stdin. + +The ``cut`` tool considers the first character in a line to have index ``1``. +The ``-c``, ``-f`` and ``-b`` switches take a parameter listing the desired +columns. This can be a single value, or a more complex list of values separated +by commas. Each value can be a single number, or two numbers separated by +hyphens representing ``low-high``. If ``low`` is unspecified, it is treated as +the first column. If ``high`` is unspecified, it is treated as being "up to the +last character (inclusive)". + +To select particular characters from each line, use the ``-c`` switch. For +particular bytes (not the same as characters when using multibyte text), use +``-b``. To specify particular fields, use ``-f``. + +When using ``-f``, the field delimiter can be specified using the ``-d`` switch. +The default value is the tab character. The ``-s`` switch instructs ``cut`` to +suppress lines which do not contain any instances of the delimiter -- by default +they are echoed intact. + +For example, to extract the second, fourth and fifth columns in a +comma-delimited file, ignoring lines which contain no commas, one could use: + +.. CODESAMPLE cut-1.ebuild + +To chop the first character off stdin, one could use: + +.. CODESAMPLE cut-2.ebuild + +See `cut-1`_ and `IEEE1003.1-2004-cut`_ for full documentation. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tools-reference/diff-and-patch/text.rst b/tools-reference/diff-and-patch/text.rst new file mode 100644 index 0000000..05d2a5a --- /dev/null +++ b/tools-reference/diff-and-patch/text.rst @@ -0,0 +1,31 @@ +diff and patch -- File Differences +================================== + +The ``diff`` tool is used to create patches (sometimes called diffs). A patch is +a program (computer science definition) which modifies text across one or more +files. Typically these are used for making changes to source code before it is +compiled. + +The simplest invocation is ``diff -u oldfile newfile``, which will create a list +of differences in unified format between ``oldfile`` and ``newfile``. To operate +over directories instead, use ``diff -urN olddir newdir``. + +.. Note:: ``cvs`` and ``svn`` provide ``cvs diff`` and ``svn diff`` respectively + which may be more helpful. + +For patches which go in the main tree, use unified (``-u``) format. This is +generally the best format to use when sending patches upstream too -- however, +occasionally you may be asked to provide context diffs, which are more portable +than unifieds (but don't handle conflicts as cleanly). In this case, use ``-c`` +rather than ``-u``. + +To apply a patch, use ``patch -pX < whatever.patch``, where ``X`` is a number +representing the number of path components which must be removed (typically this +is ``0`` or ``1``). Within ebuilds, use the ``epatch`` function instead -- see +`Patching with epatch`_. + +The `diff-1`_ and `patch-1`_ manual pages provide more information. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/tools-reference/echangelog/text.rst b/tools-reference/echangelog/text.rst new file mode 100644 index 0000000..5203625 --- /dev/null +++ b/tools-reference/echangelog/text.rst @@ -0,0 +1,15 @@ +echangelog -- ChangeLog Generation +================================== + +The ``echangelog`` tool should be used to generate ``ChangeLog`` entries. This +tool uses the ``ECHANGELOG_USER`` environment variable, which should be set in +the format ``"Your Name <luser@gentoo.org>"``. The changelog message should be +passed to ``echangelog`` on the commandline. + +``echangelog`` should be called *after* any adds, removes or updates have been +made. + +See `echangelog-1`_ for details. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tools-reference/echo/text.rst b/tools-reference/echo/text.rst new file mode 100644 index 0000000..55005bd --- /dev/null +++ b/tools-reference/echo/text.rst @@ -0,0 +1,60 @@ +echo -- Print strings +===================== + +The ``echo`` command can be used to print strings. The standard usage is ``echo +firstString secondString ...``. Also, it provides additional parameters for +formatting of the output. + +Abuse of ``echo`` +----------------- + +If you find yourself about to use ``echo`` in an ebuild, eclass or initscript, +stop and reconsider. It is almost always unnecessary. + +First of all, for printing messages in standard portage scripts, you can use +the ``einfo``, and ``eerror`` functions along with their corresponding +functions, ``einfon``, ``eerrorn``, etc, which are the same as the former, +but they won't print the trailing newline (``\n``). + +All usage of the form ``echo ${somevar} | grep substring`` just to check if the +contents of the ``${somevar}`` variable contains ``substring``, or more +often, ``echo ${somevar} | command``, are deprecated and should be (and in most +cases, can be) used as less as possible: doing so involves for no reason an +additional shell session and a pipe. The "here strings" section describes +the preferred way of dealing with such cases. + +Here Strings +------------ + +As of >=bash-2.05b, the so-called "here strings" have been +introduced. Using "here strings", you can pass contents of an +environment variable to the standard input of an application, using +``<<<word`` redirection: what actually happens is that bash +expands ``word`` and passes the result to the standard input. + +A common example would be verifying if a variable ``${foo}`` contains +the ``bar`` substring with the following construct: ``grep bar <<< +${foo}``. This replaces the deprecated and more wasteful behaviour of +using ``echo ${foo} | grep bar``. + +Standard usage of ``echo`` +-------------------------- + +In standard calls, the ``echo`` command with no additional options, outputs the +arguments passed to the standard output, separated by whitespace and with a +trailing newline character (``\n``). + +If one wants to exclude the trailing newline character, the ``-n`` option can be +passed, as in: ``echo -n "no trailing newline"``. + +Special characters, like tabs (``\t``), newline characters (``\n``), carriage +return characters (``\r``) (i.e. for translating newlines from DOS format to +Unix format), and any other ASCII character given by its code value) can be +passed to the ``echo`` command with the ``-e`` option. For example, to output +three strings, each on different lines, in a single ``echo`` command, use: +``echo -e "first line\nsecond line\nthird line"``. + +Other escape sequences and additional parameters for the ``echo`` command are +available in the man page. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/tools-reference/ekeyword/text.rst b/tools-reference/ekeyword/text.rst new file mode 100644 index 0000000..0ac64ff --- /dev/null +++ b/tools-reference/ekeyword/text.rst @@ -0,0 +1,14 @@ +ekeyword -- Keywording +====================== + +The ``ekeyword`` tool should be used to manipulate the ``KEYWORDS`` variable. +Using this tool will guarantee that you get the correct keyword ordering -- +manual editing may screw this up. The usage is ``ekeyword changes ebuilds``. +Valid changes are in the form ``sparc`` (to mark stable), ``~sparc`` (to mark +unstable), ``-sparc`` (to mark unavailable) and ``^sparc`` (to remove the +``sparc`` keyword). The special ``all`` keyword is useful when doing version +bumps -- ``ekeyword ~all foo-1.23.ebuild`` will drop all currently present +keywords to unstable. See `ekeyword-1`_ for details. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tools-reference/epkgmove/text.rst b/tools-reference/epkgmove/text.rst new file mode 100644 index 0000000..e4a20fd --- /dev/null +++ b/tools-reference/epkgmove/text.rst @@ -0,0 +1,8 @@ +epkgmove -- Package Moves +========================= + +``epkgmove`` is currently broken. Do not use it. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/tools-reference/false-and-true/text.rst b/tools-reference/false-and-true/text.rst new file mode 100644 index 0000000..519aee7 --- /dev/null +++ b/tools-reference/false-and-true/text.rst @@ -0,0 +1,8 @@ +false and true -- Generating Return Codes +========================================= + +The ``false`` utility can be used to obtain a non-zero exit code. The ``true`` +utility always produces a zero exit code. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tools-reference/find/find-1.ebuild b/tools-reference/find/find-1.ebuild new file mode 100644 index 0000000..69149db --- /dev/null +++ b/tools-reference/find/find-1.ebuild @@ -0,0 +1,5 @@ +# Header. + +find ${S} -type f | while read f ; do + einfo "Doing unholy things to ${f}" +done diff --git a/tools-reference/find/find-2.ebuild b/tools-reference/find/find-2.ebuild new file mode 100644 index 0000000..479d7e4 --- /dev/null +++ b/tools-reference/find/find-2.ebuild @@ -0,0 +1,5 @@ +# Header. + +for f in $(find ${S} -type f) ; do + einfo "Calling down holy vengance upon ${f}" +done diff --git a/tools-reference/find/find-3.ebuild b/tools-reference/find/find-3.ebuild new file mode 100644 index 0000000..9c62e4e --- /dev/null +++ b/tools-reference/find/find-3.ebuild @@ -0,0 +1,3 @@ +# Header. + +find ${S} -name '*.backup' -exec rm '{}' \; diff --git a/tools-reference/find/text.rst b/tools-reference/find/text.rst new file mode 100644 index 0000000..5266021 --- /dev/null +++ b/tools-reference/find/text.rst @@ -0,0 +1,55 @@ +find -- Finding Files +===================== + +The ``find`` utility can be used to search for and perform commands upon groups +of files matching a given set of criteria. The basic usage is ``find path rules``. + +For portability purposes, **always** specify a path. Do not rely upon +``find`` defaulting to the current working directory if no path is provided. + +Useful rules include: + +================== =========================================================== +Rule Effect +================== =========================================================== +``-name "blah"`` Only find files named ``blah``. The ``*`` and ``?`` wildcards + may be used. +``-type f`` Find only regular files, not directories. +``-type d`` Find only directories. +``-type l`` Find only symbolic links. +``-user foo`` Find only files belonging to user ``foo``. It is best to use + named users rather than numeric UIDs. In particular, ``root`` + may not be UID 0 on some systems. +``-group foo`` Find only files belonging to group ``foo``. It is best to use + named groups rather than numeric GIDs. +================== =========================================================== + +The ``-mindepth`` and ``-maxdepth`` are GNU extensions that should be avoided if +possible. + +By default, ``find`` will echo a list of matching files to the standard output. +This can be used in a ``while`` loop: + +.. CODESAMPLE find-1.ebuild + +.. Warning:: The ``die`` construct will **not work** during the above loop. See + `die and Subshells`_. + +Or a ``for`` loop (for small numbers of files): + +.. CODESAMPLE find-2.ebuild + +.. Warning:: In both cases, files with weird characters or spaces in their names + may cause serious problems. + +As an alternative, ``find`` supports a ``-exec`` argument. It accepts a command +to run, terminated by a semicolon. Inside the command, the string ``{}`` is +replaced by the name of the current matched file. Be careful with escaping to +ensure that ``bash`` doesn't gobble up the special characters: + +.. CODESAMPLE find-3.ebuild + +See `find-1`_ and `IEEE1003.1-2004-find`_ for further details and examples. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tools-reference/gentoo-syntax/text.rst b/tools-reference/gentoo-syntax/text.rst new file mode 100644 index 0000000..48acfcc --- /dev/null +++ b/tools-reference/gentoo-syntax/text.rst @@ -0,0 +1,13 @@ +gentoo-syntax -- Enhanced Vim Behaviour +======================================= + +The ``app-vim/gentoo-syntax`` package provides syntax highlighting, indent +rules, filetype settings and so on for all kinds of Gentoo things within Vim. + +Full documentation is provided with the package, and can be viewed `online +<http://svn.berlios.de/viewcvs/*checkout*/gentoo-syntax/trunk/doc/gentoo-syntax.txt>`_ +or by using ``vim``'s internal help browser (``:help gentoo-syntax``). + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/tools-reference/glep31check/text.rst b/tools-reference/glep31check/text.rst new file mode 100644 index 0000000..66c2cfe --- /dev/null +++ b/tools-reference/glep31check/text.rst @@ -0,0 +1,12 @@ +glep31check -- UTF-8 Validation +=============================== + +.. _glep31check: + +The ``glep31check`` tool can be used to validate files for `GLEP 31`_ (UTF-8) +compliance. There is no ebuild in the tree currently -- one can be obtained from +`here <http://dev.gentoo.org/~ciaranm/overlay/app-portage/glep31check/>`__. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/tools-reference/grep/text.rst b/tools-reference/grep/text.rst new file mode 100644 index 0000000..3f99689 --- /dev/null +++ b/tools-reference/grep/text.rst @@ -0,0 +1,36 @@ +grep -- Text Filtering +====================== + +The ``grep`` tool can be used to extract lines matching a given regular +expression from a file, or to check whether a given regular expression matches +any line in a file. + +The usage is ``grep "pattern" files``. If no files are specified, text is read +from the standard input. The "pattern" is a standard basic regular expression, +as described in `IEEE1003.1-2004-9.3`_. + +If the ``-E`` argument is supplied, ``pattern`` is treated as being an extended +regular expression as described in `IEEE1003.1-2004-9.4`_. + +If the ``-F`` argument is supplied, ``pattern`` is treated as being a fixed +string rather than a regular expression. + +By default, ``grep`` prints out matching lines from the input. If ``-q`` is +specified, no output is displayed. If ``-l`` (lowercase letter ell) is +specified, only the filenames of files which contain matching lines are +displayed. + +The ``-v`` option can be used to select lines which do *not* match the pattern. + +The ``-s`` option can be used to suppress messages about nonexistent or +unreadable files. + +The return code can be used to test whether or not a match occurred. A return +code of ``0`` indicates that one or more matches occurred; a code of ``1`` +indicates no matches. + +See `IEEE1003.1-2004-grep`_ for details. The `grep-1`_ manual page on GNU systems +documents many non-portable additional features. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tools-reference/head-and-tail/head-and-tail-1.ebuild b/tools-reference/head-and-tail/head-and-tail-1.ebuild new file mode 100644 index 0000000..70a51dc --- /dev/null +++ b/tools-reference/head-and-tail/head-and-tail-1.ebuild @@ -0,0 +1,25 @@ +# Header. + +# bad: get the first five lines of input.txt with all 'foo' +# replaced with 'bar' +head -n 5 input.txt | sed -e 's/foo/bar/g' > output.txt + +# good: use sed's address ranges and command groups to do +# the same thing with only one fork +sed -n -e '1,5{ s/foo/bar/g ; p }' input.txt > output.txt + +# good: another way is with an extra command which exits +# on line 5 +sed -n -e 's/foo/bar/gp ; 5q' input.txt > output.txt + +# bad: set foo to the first line containing somestring +foo=$(sed -n -e '/somestring/p' input.txt | head -n 1 ) + +# good: use early exit to do the same thing in pure sed +foo=$(sed -n -e '/somestring/{ p ; q }' input.txt ) + +# bad: output the last line matching 'somestring' +sed -n -e '/somestring/p' input.txt | tail -n 1 + +# good: do this in pure sed using the hold space +sed -n -e '/somestring/h ; ${ x ; p }' diff --git a/tools-reference/head-and-tail/head-and-tail-2.ebuild b/tools-reference/head-and-tail/head-and-tail-2.ebuild new file mode 100644 index 0000000..68d3dd4 --- /dev/null +++ b/tools-reference/head-and-tail/head-and-tail-2.ebuild @@ -0,0 +1,4 @@ +# Header. + +sed -n -e '123p' + diff --git a/tools-reference/head-and-tail/text.rst b/tools-reference/head-and-tail/text.rst new file mode 100644 index 0000000..28ac0cb --- /dev/null +++ b/tools-reference/head-and-tail/text.rst @@ -0,0 +1,40 @@ +head and tail -- Line Extraction +================================ + +The ``head`` and ``tail`` utilities can be used to obtain only the first or last +parts of a file respectively. Both will read from the files named on the +commandline, or stdin if no files are provided. + +The ``head`` utility takes a single argument, ``-n``, which must be followed by +an integer indicating the desired number of lines to be displayed. + +.. Warning:: Use of the GNU ``-c`` option is unportable and should be avoided. + +For full details, see `IEEE1003.1-2004-head`_. Note that `head-1`_ on GNU +systems describes many non-portable options. + +The ``tail`` utility is similar, but takes lines from the *end* of the file. The +``-n`` argument specifies how many lines to display. + +To specify "the last five lines", use ``tail -n5``. To specify "all but the +first five lines", use ``tail -n+5``. + +For full details, see `IEEE1003.1-2004-tail`_. Note that `tail-1`_ on GNU +systems describes many non-portable options. + +Chaining ``head`` or ``tail`` with ``sed`` +------------------------------------------ + +Chaining ``head`` or ``tail`` with ``sed`` is usually unnecessary. Use of +addresses and early exit can do the same thing with a single ``sed`` call: + +.. CODESAMPLE head-and-tail-1.ebuild + +``tail -n X`` where X is larger than one is possible to do in pure +``sed`` but tricky. Using chained commands here is probably simplest. + +Finally, to extract a single specific line, use ``sed`` instead: + +.. CODESAMPLE head-and-tail-2.ebuild + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/tools-reference/sed/sed-1.ebuild b/tools-reference/sed/sed-1.ebuild new file mode 100644 index 0000000..039633f --- /dev/null +++ b/tools-reference/sed/sed-1.ebuild @@ -0,0 +1,6 @@ +# Header. + +# This plugin is mapped to the 'h' key by default, which conflicts with some +# other mappings. Change it to use 'H' instead. +sed -i 's/\(noremap <buffer> \)h/\1H/' info.vim \ + || die 'sed failed' diff --git a/tools-reference/sed/sed-10.ebuild b/tools-reference/sed/sed-10.ebuild new file mode 100644 index 0000000..3f08563 --- /dev/null +++ b/tools-reference/sed/sed-10.ebuild @@ -0,0 +1,4 @@ +# Header. + +# Replace any "emacs" instances (ignoring case) with "Vim" +sed -i -e 's/emacs/Vim/gi' editors.txt || die "Ouch" diff --git a/tools-reference/sed/sed-11.ebuild b/tools-reference/sed/sed-11.ebuild new file mode 100644 index 0000000..a9f7e20 --- /dev/null +++ b/tools-reference/sed/sed-11.ebuild @@ -0,0 +1,12 @@ +# Header. + +# Add 'Bob' after the 'To:' line: +sed -i -e '/^To: $/a Bob' data.in || die "Oops" + +# Add 'From: Alice' before the 'To:' line: +sed -i -e '/^To: $/i From: Alice' + +# Note that the spacing between the 'i' or 'a' and 'Bob' or 'From: Alice' is simply ignored' + +# Add 'From: Alice' indented by two spaces: (You only need to escape the first space) +sed -i -e '/^To: $/i\ From: Alice' diff --git a/tools-reference/sed/sed-2.ebuild b/tools-reference/sed/sed-2.ebuild new file mode 100644 index 0000000..74ad731 --- /dev/null +++ b/tools-reference/sed/sed-2.ebuild @@ -0,0 +1,13 @@ +# Header. + +# Add in the Gentoo -r number to fluxbox -version output. We need to look +# for the line in version.h.in which contains "__fluxbox_version" and append +# our content to it. +if [[ "${PR}" == "r0" ]] ; then + suffix="gentoo" +else + suffix="gentoo-${PR}" +fi +sed -i \ + -e "s~\(__fluxbox_version .@VERSION@\)~\1-${suffix}~" \ + version.h.in || die "version sed failed" diff --git a/tools-reference/sed/sed-3.ebuild b/tools-reference/sed/sed-3.ebuild new file mode 100644 index 0000000..043a1c4 --- /dev/null +++ b/tools-reference/sed/sed-3.ebuild @@ -0,0 +1,11 @@ +# Header. + +# This plugin uses an 'automatic HelpExtractor' variant. This causes +# problems for us during the unmerge. Fortunately, sed can fix this +# for us. First, we extract the documentation: +sed -e '1,/^" HelpExtractorDoc:$/d' \ + ${S}/plugin/ZoomWin.vim > ${S}/doc/ZoomWin.txt \ + || die "help extraction failed" +# Then we remove the help extraction code from the plugin file: +sed -i -e '/^" HelpExtractor:$/,$d' ${S}/plugin/ZoomWin.vim \ + || die "help extract remove failed" diff --git a/tools-reference/sed/sed-4.ebuild b/tools-reference/sed/sed-4.ebuild new file mode 100644 index 0000000..05b1d3f --- /dev/null +++ b/tools-reference/sed/sed-4.ebuild @@ -0,0 +1,8 @@ +# Header. + +sed [ option flags ] \ + -e 'first command' \ + -e 'second command' \ + -e 'and so on' \ + input-file > output-file \ + || die "Oops, sed didn't work!" diff --git a/tools-reference/sed/sed-5.ebuild b/tools-reference/sed/sed-5.ebuild new file mode 100644 index 0000000..1e4d9fa --- /dev/null +++ b/tools-reference/sed/sed-5.ebuild @@ -0,0 +1,6 @@ +# Header. + +# replace all instances of "some text" with "different content" in +# somefile.txt +sed -i -e 's/some text/different content/g' somefile.txt || \ + die "Sed broke!" diff --git a/tools-reference/sed/sed-6.ebuild b/tools-reference/sed/sed-6.ebuild new file mode 100644 index 0000000..66b75c8 --- /dev/null +++ b/tools-reference/sed/sed-6.ebuild @@ -0,0 +1,5 @@ +# Header. + +# replace all instances of "/usr/local" with "/usr" +sed -i -e 's~/usr/local~/usr~g' somefile.txt || \ + die "sed broke" diff --git a/tools-reference/sed/sed-7.ebuild b/tools-reference/sed/sed-7.ebuild new file mode 100644 index 0000000..c7d9aa8 --- /dev/null +++ b/tools-reference/sed/sed-7.ebuild @@ -0,0 +1,4 @@ +# Header. + +# Replace any "hello"s which occur at the start of a line with "howdy". +sed -i -e 's!^hello!howdy!' data.in || die "sed failed" diff --git a/tools-reference/sed/sed-8.ebuild b/tools-reference/sed/sed-8.ebuild new file mode 100644 index 0000000..7ee3808 --- /dev/null +++ b/tools-reference/sed/sed-8.ebuild @@ -0,0 +1,4 @@ +# Header. + +# Replace any "bye"s which occur at the end of a line with "cheerio!". +sed -i -e 's,bye$,cheerio!,' data.in || die "sed failed" diff --git a/tools-reference/sed/sed-9.ebuild b/tools-reference/sed/sed-9.ebuild new file mode 100644 index 0000000..c0dce41 --- /dev/null +++ b/tools-reference/sed/sed-9.ebuild @@ -0,0 +1,5 @@ +# Header. + +# Replace any lines which are exactly "change this line" with "have a +# cookie". +sed -i -e 's-^change this line$-have a cookie-' data.in || die "Oops" diff --git a/tools-reference/sed/text.rst b/tools-reference/sed/text.rst new file mode 100644 index 0000000..5ab0158 --- /dev/null +++ b/tools-reference/sed/text.rst @@ -0,0 +1,338 @@ +sed -- Stream Editor +==================== + +Sometimes it is better to use regular expressions to manipulate content rather +than patching sources. This can be used for small changes, especially those +which are likely to create patch conflicts across versions. The canonical way of +doing this is via ``sed``: + +.. CODESAMPLE sed-1.ebuild + +Another common example is appending a ``-gentoo-blah`` version string (some +upstreams like us to do this so that they can tell exactly which package they're +dealing with). Again, we can use ``sed``. Note that the ``${PR}`` variable will +be set to ``r0`` if we don't have a ``-r`` component in our version. + +.. CODESAMPLE sed-2.ebuild + +It is also possible to extract content from existing files to create new files +this way. Many ``app-vim`` ebuilds use this technique to extract documentation +from the plugin files and convert it to Vim help format. + +.. CODESAMPLE sed-3.ebuild + +A summary of the more common ways of using ``sed`` and a description of +commonly used address and token patterns follows. Note that some of these +constructs are specific to ``GNU sed 4`` -- on non-GNU userland archs, the +``sed`` command must be aliased to GNU sed. Also note that ``GNU sed 4`` is +guaranteed to be installed as part of ``system``. This was not always the case, +which is why some packages, particularly those which use ``sed -i``, have +``DEPEND`` s upon ``>=sys-apps/sed-4``. + +Basic ``sed`` Invocation +------------------------ + +The basic form of a call is: + +.. CODESAMPLE sed-4.ebuild + +For cases where the input and output files are the same, the inplace option +should be used. This is done by passing ``-i`` as one of the option flags. + +Usually ``sed`` prints out every line of the created content. To obtain only +explicitly printed lines, the ``-n`` flag should be used. + +.. Note:: The term *pattern* refers to the description of text being matched. + +Simple Text Substitution using ``sed`` +--------------------------------------- + +The commonest form of ``sed`` is to replace all instances of ``"some text"`` +with ``"different content"``. This is done as follows: + +.. CODESAMPLE sed-5.ebuild + +.. Note:: The ``/g`` flag is required to replace *all* occurrences. Without this + flag, only the first match on each line is replaced. + +.. Warning:: The above will replace ``"irksome texting"`` with + ``"irkdifferent contenting"``, which may not be desired. + +If the pattern or the replacement string contains the forward slash character, +it is usually easiest to use a different delimiter. Most punctuation characters +are allowed, although backslash and any form of brackets should be avoided. + +.. CODESAMPLE sed-6.ebuild + +Patterns can be made to match only at the start or end of a line by using the +``^`` and ``$`` metacharacters. A ``^`` means "match at the start of a line +only", and ``$`` means "match at the end of a line only". By using both in a +single statement, it is possible to match exact lines. + +.. CODESAMPLE sed-7.ebuild + +.. Note:: There is no need for a ``!g`` suffix here. + +.. CODESAMPLE sed-8.ebuild + +.. CODESAMPLE sed-9.ebuild + +To ignore case in the pattern, add the ``/i`` flag. + +.. CODESAMPLE sed-10.ebuild + +.. Warning:: Case insensitive matching doesn't work correctly when backreferences + are used. + +Regular Expression Substitution using ``sed`` +--------------------------------------------- + +It is also possible to do more complex matches with ``sed``. Some examples could +be: + +* Match any three digits +* Match either "foo" or "bar" +* Match any of the letters "a", "e", "i", "o" or "u" + +These types of pattern can be chained together, leading to things like "match +any vowel followed by two digits followed by either foo or bar". + +To match any of a set of characters, a *character class* can be used. These come +in three forms. + +* A backslash followed by a letter. ``\d``, for example, matches a single digit + (any of 0, 1, 2, ... 9). ``\s`` matches a single whitespace character. A table + of the more useful classes is provided later in this document. +* A group of characters inside square brackets. ``[aeiou]``, for example, + matches any one of 'a', 'e', 'i', 'o' or 'u'. Ranges are allowed, such as + ``[0-9A-Fa-fxX]``, which could be used to match any hexadecimal digit or the + characters 'x' and 'X'. Inverted character classes, such as ``[^aeiou]``, + match any single character *except* those listed. +* A POSIX character class is a special named group of characters that are + locale-aware. For example, ``[[:alpha:]]`` matches any 'alphabet' character in + the current locale. A table of the more useful classes is provided later in + this document. + +.. Note:: The regex ``a[^b]`` does **not** mean "match a, so long as it does not + have a 'b' after it". It means "match a followed by exactly one character which + is not a 'b'". This is important when one considers a line ending in the + character 'a'. + +.. Note:: At the time of writing, the ``sed`` documentation (`sed-1`_ and + ``sed.info``) does not mention that POSIX character classes are supported. + Consult `IEEE1003.1-2004-9.3`_ for full details of how these *should* work, and + the ``sed`` source code for full details of how these *actually* work. + +To match any one of multiple options, *alternation* can be used. The basic form +is ``first\|second\|third``. + +To group items to avoid ambiguity, the ``\(parentheses\)`` construct may be +used. To match "iniquity" or "infinity", one could use ``in\(iqui\|fini\)ty``. + +To optionally match an item, add a ``\?`` after it. For example, ``colou\?r`` +matches both "colour" and "color". This can also be applied to character classes +and groups in parentheses, for example ``\(in\)\?finite\(ly\)\?``. Further atoms +are available for matching "one or more", "zero or more", "at least n", "between +n and m" and so on -- these are summarised later in this document. + +There are also some special constructs which can be used in the replacement part +of a substitution command. To insert the contents of the pattern's first matched +bracket group, use ``\1``, for the second use ``\2`` and so on up to ``\9``. An +unescaped ampersand ``&`` character can be used to insert the entire contents of +the match. These and other replace atoms are summarised later in this document. + +Addresses in ``sed`` +-------------------- + +Many ``sed`` commands can be applied only to a certain line or range of lines. +This could be useful if one wishes to operate only on the first ten lines of a +document, for example. + +The simplest form of address is a single positive integer. This will cause the +following command to be applied only to the line in question. Line numbering +starts from 1, but the address 0 can be useful when one wishes to insert text +*before* the first line. If the address 100 is used on a 50 line document, the +associated command will never be executed. + +To match the last line in a document, the ``$`` address may be used. + +To match any lines that match a given regular expression, the form +``/pattern/`` is allowed. This can be useful for finding a particular line and +then making certain changes to it -- sometimes it is simpler to handle this in +two stages rather than using one big scary ``s///`` command. When used in +ranges, it can be useful for finding all text between two given markers or +between a given marker and the end of the document. + +To match a range of addresses, ``addr1,addr2`` can be used. Most address +constructs are allowed for both the start and the end addresses. + +Addresses may be inverted with an exclamation mark. To match all lines *except* +the last, ``$!`` may be used. + +Finally, if no address is given for a command, the command is applied to every +line in the input. + +.. Note:: GNU ``sed`` does **not** support the ``%`` address forms found in some + other implementations. It also doesn't support ``/addr/+offset``, that's an + ``ex`` thing... + +Other more complex options involving chaining addresses are available. These are +not discussed in this document. + +Content Deletion using ``sed`` +------------------------------ + +Lines may be deleted from a file using ``address d`` command. To delete the +third line of a file, one could use ``3d``, and to filter out all lines +containing "fred", ``/fred/d``. + +.. Note:: sed -e ``/fred/d`` is *not* the same as ``s/.*fred.*//`` -- the former + will delete the lines including the newline, whereas the latter will delete the + lines' contents but not the newline. + +Content Extraction using ``sed`` +-------------------------------- + +When the ``-n`` option is passed to ``sed``, no output is printed by default. +The ``p`` command can be used to display content. For example, to print lines +containing "infra monkey", the command ``sed -n -e '/infra monkey/p'`` could be +used. Ranges may also be printed -- ``sed -n -e '/^START$/,/^END$/p'`` is +sometimes useful. + +Inserting Content using ``sed`` +------------------------------- + +To insert text with sed use a ``address a`` or ``i`` command. The +``a`` command inserts on the line following the match while the ``i`` +command inserts on the line before the match. + +As usual, an address can be either a line number or a regular +expression: a line number command will only be executed once and a +regular expression insert/append will be executed for each match. + +.. CODESAMPLE sed-11.ebuild + +Note that you should use a match instead of a line number wherever +possible. This reduces problems if a line is added at the beginning of +the file, for example, causing your sed script to break. + +Regular Expression Atoms in ``sed`` +----------------------------------- + +Basic Atoms +''''''''''' + +================================== ========================== +Atom Purpose +================================== ========================== +``text`` Literal text +``\( \)`` Grouping +``\|`` Alternation, a *or* b +``*`` ``\?`` ``\+`` ``\{\}`` Repeats, see below +``.`` Any single character +``^`` Start of line +``$`` End of line +``[abc0-9]`` Any one of +``[^abc0-9]`` Any one character except +``[[:alpha:]]`` POSIX character class, see below +``\1`` .. ``\9`` Backreference +``\x`` (any special character) Match character literally +``\x`` (normal characters) Shortcut, see below +================================== ========================== + +Character Class Shortcuts +''''''''''''''''''''''''' + +========= ========================== +Atom Description +========= ========================== +``\a`` "BEL" character +``\f`` "Form Feed" character +``\t`` "Tab" character +``\w`` "Word" (a letter, digit or underscore) character +``\W`` "Non-word" character +========= ========================== + + +POSIX Character Classes +''''''''''''''''''''''' + +Read the source, it's the only place these're documented properly... + +================= ========================== +Class Description +================= ========================== +``[[:alpha:]]`` Alphabetic characters +``[[:upper:]]`` Uppercase alphabetics +``[[:lower:]]`` Lowercase alphabetics +``[[:digit:]]`` Digits +``[[:alnum:]]`` Alphabetic and numeric characters +``[[:xdigit:]]`` Digits allowed in a hexadecimal number +``[[:space:]]`` Whitespace characters +``[[:print:]]`` Printable characters +``[[:punct:]]`` Punctuation characters +``[[:graph:]]`` Non-blank characters +``[[:cntrl:]]`` Control characters +================= ========================== + +Count Specifiers +'''''''''''''''' + +============= ========================== +Atom Description +============= ========================== +``*`` Zero or more (greedy) +``\+`` One or more (greedy) +``\?`` Zero or one (greedy) +``\{N\}`` Exactly N +``\{N,M\}`` At least N and no more than M (greedy) +``\{N,\}`` At least N (greedy) +============= ========================== + +Replacement Atoms in ``sed`` +---------------------------- + +================== ============================= +Atom Description +================== ============================= +``\1`` .. ``\9`` Captured ``\( \)`` contents +``&`` The entire matched text +``\L`` All subsequent characters are converted to lowercase +``\l`` The following character is converted to lowercase +``\U`` All subsequent characters are converted to uppercase +``\u`` The following character is converted to uppercase +``\E`` Cancel the most recent ``\L`` or ``\U`` +================== ============================= + + +Details of ``sed`` Match Mechanics +---------------------------------- + +GNU ``sed`` uses a traditional (non-POSIX) nondeterministic finite automaton with +extensions to support capturing to do its matching. This means that in all +cases, the match with the leftmost starting position will be favoured. Of all +the leftmost possible matches, favour will be given to leftmost alternation +options. Finally, all other things being equal favour will be given to the +longest of the leftmost counting options. + +Most of this is in violation of one of the sillier POSIX rules, so it's best not +to rely upon it. It *is* safe to assume that ``sed`` will always pick the leftmost +match, and that it will match greedily with priority given to items earlier in +the pattern. + +Notes on Performance with ``sed`` +--------------------------------- + +.. Todo:: write this + +Recommended Further Reading for Regular Expressions +--------------------------------------------------- + +The author recommends *Mastering Regular Expressions* by Jeffrey E. F. Friedl +for those who wish to learn more about regexes. This text is remarkably devoid +of phrases like "let ``t`` be a finite contiguous sequence such that ``t[n] ∈ ∑ +∀ n``", and was *not* written by someone whose pay cheque depended upon them being +able to express simple concepts with pages upon pages of mathematical and Greek +symbols. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. diff --git a/tools-reference/sort/text.rst b/tools-reference/sort/text.rst new file mode 100644 index 0000000..0c90a93 --- /dev/null +++ b/tools-reference/sort/text.rst @@ -0,0 +1,15 @@ +sort -- Sorting Text +==================== + +The ``sort`` tool can be used to sort text. It sorts the contents of the files +named on the commandline, or the text provided on standard input if no files are +given. Output is to standard output by default, unless a ``-o filename`` option +is provided. + +To ignore case, the ``-f`` switch may be used. + +Many other options are available. See `sort-1`_ and `IEEE1003.1-2004-sort`_ for +details. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tools-reference/text.rst b/tools-reference/text.rst new file mode 100644 index 0000000..56cc0c2 --- /dev/null +++ b/tools-reference/text.rst @@ -0,0 +1,11 @@ +Tools +===== + +This section provides an overview of various useful standard Unix and Gentoo +tools and utilities that may be used within ebuilds or when working with +ebuilds. + +.. CHILDLIST + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + diff --git a/tools-reference/tr/text.rst b/tools-reference/tr/text.rst new file mode 100644 index 0000000..63dff78 --- /dev/null +++ b/tools-reference/tr/text.rst @@ -0,0 +1,30 @@ +tr -- Character Translation +=========================== + +The ``tr`` command can be used to translate, squeeze and delete character +sequences. See `tr-1`_ and `IEEE1003.1-2004-tr`_ for the full specification. + +.. Note:: ``tr``, unlike most other utilities, only reads from standard input + and only writes to standard output. Therefore, you will have to use + ``tr [options] < input > output``. + +``tr`` operates in a number of modes, depending upon the invocation: + +Deleting characters + To delete all occurrences of certain characters, use ``tr -d asdf``. + +Deleting repeated characters + To replace repeated characters with a single character ('squeeze'), use + ``tr -s asdf``. + +Transliterating characters + To replace all 'a' characters with '1', all 'b' with '2' and all 'c' with + '3', use ``tr abc 123``. + +Certain special forms are allowed for the arguments. ``a-z`` expands to all +characters from 'a' to 'z', ``\t`` represents a tab and so on. See the +documentation for a full list. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + + diff --git a/tools-reference/uniq/text.rst b/tools-reference/uniq/text.rst new file mode 100644 index 0000000..e2bc402 --- /dev/null +++ b/tools-reference/uniq/text.rst @@ -0,0 +1,12 @@ +uniq -- Filtering Duplicates +============================ + +The ``uniq`` utility can be used to filter **adjacent** duplicate lines in files +or in the text provided through standard input. + +.. Note:: Instead of using ``sort | uniq``, one should use ``sort -u``. + +See `uniq-1`_ and `IEEE1003.1-2004-uniq`_ for details. + +.. vim: set ft=glep tw=80 sw=4 et spell spelllang=en : .. + |
