diff options
author | Diego Elio 'Flameeyes' Pettenò <flameeyes@gmail.com> | 2010-01-06 21:27:53 +0100 |
---|---|---|
committer | Diego Elio 'Flameeyes' Pettenò <flameeyes@gmail.com> | 2010-01-06 21:27:53 +0100 |
commit | 20e1b4ff7e2e4d307c71b183ea45d1dd61508dd4 (patch) | |
tree | d9397cf19176a6005afa45722252b23b87fa0555 | |
parent | More translations. (diff) | |
download | devmanual-20e1b4ff7e2e4d307c71b183ea45d1dd61508dd4.tar.gz devmanual-20e1b4ff7e2e4d307c71b183ea45d1dd61508dd4.tar.bz2 devmanual-20e1b4ff7e2e4d307c71b183ea45d1dd61508dd4.zip |
More chapters.
-rw-r--r-- | chunk.toc | 4 | ||||
-rw-r--r-- | content/general-concepts.xmli | 4 | ||||
-rw-r--r-- | content/general-concepts/dependencies.xmli | 2 | ||||
-rw-r--r-- | content/general-concepts/overlay.xmli | 47 | ||||
-rw-r--r-- | content/general-concepts/portage-cache.xmli | 76 | ||||
-rw-r--r-- | content/general-concepts/sandbox.xmli | 26 | ||||
-rw-r--r-- | content/general-concepts/slotting.xmli | 49 |
7 files changed, 207 insertions, 1 deletions
@@ -18,6 +18,10 @@ <d:tocentry linkend="general-concepts.install-destinations"><?dbhtml filename="general-concepts/install-destinations/index.html"?></d:tocentry> <d:tocentry linkend="general-concepts.licenses"><?dbhtml filename="general-concepts/licenses/index.html"?></d:tocentry> <d:tocentry linkend="general-concepts.mirrors"><?dbhtml filename="general-concepts/mirrors/index.html"?></d:tocentry> + <d:tocentry linkend="general-concepts.overlay"><?dbhtml filename="general-concepts/overlay/index.html"?></d:tocentry> + <d:tocentry linkend="general-concepts.portage-cache"><?dbhtml filename="general-concepts/portage-cache/index.html"?></d:tocentry> + <d:tocentry linkend="general-concepts.sandbox"><?dbhtml filename="general-concepts/sandbox/index.html"?></d:tocentry> + <d:tocentry linkend="general-concepts.slotting"><?dbhtml filename="general-concepts/slotting/index.html"?></d:tocentry> </d:tocentry> </toc> diff --git a/content/general-concepts.xmli b/content/general-concepts.xmli index 217661e..05f0c3d 100644 --- a/content/general-concepts.xmli +++ b/content/general-concepts.xmli @@ -28,5 +28,9 @@ <xi:include parse="xml" href="general-concepts/licenses.xmli" /> <!-- <xi:include parse="xml" href="general-concepts/linguas.xmli" /> --> <xi:include parse="xml" href="general-concepts/mirrors.xmli" /> + <xi:include parse="xml" href="general-concepts/overlay.xmli" /> + <xi:include parse="xml" href="general-concepts/portage-cache.xmli" /> + <xi:include parse="xml" href="general-concepts/sandbox.xmli" /> + <xi:include parse="xml" href="general-concepts/slotting.xmli" /> </part> diff --git a/content/general-concepts/dependencies.xmli b/content/general-concepts/dependencies.xmli index e7333db..39e04f3 100644 --- a/content/general-concepts/dependencies.xmli +++ b/content/general-concepts/dependencies.xmli @@ -207,7 +207,7 @@ DEPEND=">=dev-libs/openssl-0.9.7d" </section> </section> - <section> + <section xml:id="general-concepts.dependencies.slot-dependencies"> <title>SLOT Dependencies</title> <para> diff --git a/content/general-concepts/overlay.xmli b/content/general-concepts/overlay.xmli new file mode 100644 index 0000000..406b091 --- /dev/null +++ b/content/general-concepts/overlay.xmli @@ -0,0 +1,47 @@ +<?xml version="1.0" encoding="utf-8"?> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xl="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="general-concepts.overlay"> + + <title>Overlay</title> + + <para> + Portage can look in multiple places for packages by using an overlay. The locations of overlays are controlled by + the <varname>PORTDIR_OVERLAY</varname> variable, which should contain a space-separated list of paths. + </para> + + <para> + The overlay should contain the same directory structure as <varname>PORTDIR</varname> (although only the necessary + directories need be included). For example, a simple overlay might have a directory structure like: + </para> + + <programlisting><![CDATA[ +overlay +|-- dev-util + `-- gengetopt + |-- Manifest + |-- files + | `-- gengetopt-2.13-foobar.patch + `-- gengetopt-2.13.ebuild +]]></programlisting> + + <para> + An overlay can be used to 'add' items to the tree (although you must ensure that + <filename>/etc/portage/categories</filename> is used if any new categories are added) or to override existing + entries. + </para> + + <section> + <title>Overlay and Eclasses</title> + + <para> + 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 an overlay (see + <xref linkend="appendices.common-problems.eclass-inherited-illegally"/>). To be safe, manually + <command>touch</command> all relevant overlay files after updating overlay eclasses. + </para> + </section> + +</chapter> diff --git a/content/general-concepts/portage-cache.xmli b/content/general-concepts/portage-cache.xmli new file mode 100644 index 0000000..939a1f7 --- /dev/null +++ b/content/general-concepts/portage-cache.xmli @@ -0,0 +1,76 @@ +<?xml version="1.0" encoding="utf-8"?> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xl="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="general-concepts.portage-cache"> + + <title>The Portage Cache</title> + + <para> + Portage uses a cache for most top-level variables (<varname>DEPEND</varname>, <varname>DESCRIPTION</varname>, + <varname>SRC_URI</varname> 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 (<varname>P</varname>, + <varname>PN</varname>, <varname>PV</varname>, <varname>PR</varname>, <varname>PVR</varname> and + <varname>PF</varname>). + </para> + + <para> + So, the following will not work: + </para> + + <programlisting language="ebuild"><![CDATA[ +# DO NOT DO THIS! +if ! has_version "x11-libs/gtk+" ; then + DEPEND="${DEPEND} + gtk? ( >=x11-libs/gtk+-2 ) + !gtk? ( =x11-libs/gtk+-1.2* )" +fi +]]></programlisting> + + <para> + However, this is legal, since <varname>versionator.eclass</varname> works upon <varname>PV</varname>, and + <varname>PV</varname> and <varname>PN</varname> are both static: + </para> + + <programlisting language="ebuild"><![CDATA[ +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 +]]></programlisting> + + <section> + <title>Conditional Inherits</title> + + <para> + 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 <varname>USE</varname> flags + are illegal, but inherits based solely upon <varname>PN</varname> are allowed. + </para> + + <para> + As an example of a legal and possibly useful conditional inherit, some eclasses do: + </para> + + <programlisting language="ebuild"><![CDATA[ +if [[ "${PN##*-}" == "cvs" ]] ; then + inherit cvs +fi +]]></programlisting> + + <para> + This allows the same eclass to be used for both regular and <package>-cvs</package> packages. + </para> + </section> +</chapter> diff --git a/content/general-concepts/sandbox.xmli b/content/general-concepts/sandbox.xmli new file mode 100644 index 0000000..dcf68cf --- /dev/null +++ b/content/general-concepts/sandbox.xmli @@ -0,0 +1,26 @@ +<?xml version="1.0" encoding="utf-8"?> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xl="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="general-concepts.sandbox"> + <title>Sandbox</title> + + <para> + During the <function>src_unpack</function>, <function>src_compile</function>, <function>src_test</function> and + <function>src_install</function> phases, <filename>ebuild.sh</filename> operates inside a + <emphasis>sandbox</emphasis>. 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. + </para> + + <para> + <emphasis>All packages must build correctly when sandbox is active.</emphasis> 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 <filename>Makefile</filename> won't cause problems. Using + <command>addwrite</command> is generally <emphasis>not</emphasis> the correct solution. + </para> + + <para> + See <xref linkend="function-reference.sandbox-functions"/> for details on sandbox-related functions. See <xref + linkend="appendices.common-problems.access-violations"/> for suggestions on fixing sandbox-related build problems. + </para> +</chapter> diff --git a/content/general-concepts/slotting.xmli b/content/general-concepts/slotting.xmli new file mode 100644 index 0000000..c80b09c --- /dev/null +++ b/content/general-concepts/slotting.xmli @@ -0,0 +1,49 @@ +<?xml version="1.0" encoding="utf-8"?> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xl="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + xml:id="general-concepts.slotting"> + <title>Slotting</title> + + <para> + Packages can support having multiple versions installed simultaneously. This is useful for libraries which may have + changed interfaces between versions — for example, the <package>gtk+</package> package can install both versions + <literal>1.2</literal> and <literal>2.6</literal> in parallel. This feature is called slotting. + </para> + + <para> + Most packages have no need for slotting. These packages specify <literal>SLOT="0"</literal> in the ebuilds. This is + <emphasis>not</emphasis> the same as specifying an empty slot — an empty slot means "disable slotting entirely", and + should not be used. + </para> + + <para> + Portage permits at most one instance of a package installation <emphasis>per <varname>SLOT</varname> + value</emphasis>. For example, say we have the following: + </para> + + <itemizedlist> + <listitem><para><package>foo-1.1</package> with <literal>SLOT="1"</literal></para></listitem> + <listitem><para><package>foo-1.2</package> with <literal>SLOT="1"</literal></para></listitem> + <listitem><para><package>foo-2.0</package> with <literal>SLOT="2"</literal></para></listitem> + <listitem><para><package>foo-2.1</package> with <literal>SLOT="2"</literal></para></listitem> + </itemizedlist> + + <para> + Then the user could have, say, <package>foo-1.2</package> and <package>foo-2.0</package> installed in parallel, + but <emphasis>not</emphasis> <package>foo-1.1</package> and <package>foo-1.2</package>. Note that it is entirely + possible that the user may have <package>foo-2.0</package> installed and no <package>foo-1.x</package> at all. + </para> + + <para> + To <varname>DEPEND</varname> upon a package in a specific slot, refer to <xref + linkend="general-concepts.dependencies.slot-dependencies"/>. + </para> + + <para> + Currently portage will accept an arbitrary string for the value of <varname>SLOT</varname>. 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. + </para> +</chapter> |