diff options
| author |   Mark Loeser <halcy0n@gentoo.org> | 2006-05-03 05:24:54 +0000 |
|---|---|---|
| committer | Mark Loeser <halcy0n@gentoo.org> | 2006-05-03 05:24:54 +0000 |
| commit | 46e0bbce1cab97b532310a22973ee12d08d9fe78 (patch) | |
| tree | 6a65ebb62c21895bb160380d228b7c1dfa3e4e4c /appendices/common-problems | |
| parent | This should have been an important tag, but wasn't (diff) | |
| download | devmanual-46e0bbce1cab97b532310a22973ee12d08d9fe78.tar.gz devmanual-46e0bbce1cab97b532310a22973ee12d08d9fe78.tar.bz2 devmanual-46e0bbce1cab97b532310a22973ee12d08d9fe78.zip | |
Adding the last xml files, then I'll fix all of the addresses in one shot
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@38 176d3534-300d-0410-8db8-84e73ed771c3
Diffstat (limited to 'appendices/common-problems')
| -rw-r--r-- | appendices/common-problems/text.xml | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/appendices/common-problems/text.xml b/appendices/common-problems/text.xml new file mode 100644 index 0000000..35b642d --- /dev/null +++ b/appendices/common-problems/text.xml @@ -0,0 +1,244 @@ +<?xml version="1.0"?> +<guide self="appendices/common-problems/"> +<chapter> +<title>Common Problems</title> +<body> + +<p> +This page provides suggestions on how to handle various commonly seen errors +and QA notices. +</p> + +<section> +<title>Handling QA Notices</title> +<body> + +<p> +The <c>ebuild.sh</c> 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 <d/> they are not a +substitute for proper testing and QA by developers. +</p> + +<note> +Some eclasses output messages in the same format. These are not +covered here. +</note> + +<subsection> +<title>QA Notice <d/> USE Flag foo not in IUSE</title> +<body> + +<p> +With the exception of 'special' flags (the arch flags and <c>USE_EXPAND</c> +variables), all <c>USE</c> flags used by a package must be included in <c>IUSE</c>. +See `IUSE`_ and `USE Flags`_. +</p> + +</body> +</subsection> + +<subsection> +<title>QA Notice <d/> foo in global scope</title> +<body> + +<p> +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: +</p> + +<dl> + <dt> + <c>sed</c>, <c>awk</c>, <c>grep</c>, <c>egrep</c>, <c>cut</c> etc + </dt> + <dd> + <p> + 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 <c>bash</c> constructs. The <c>versionator</c> eclass is often of use here. + See `Version Formatting Issues`_, `versionator.eclass-5`_ and `Bash Variable + Manipulation`_. + </p> + </dd> + <dt> + <c>has_version</c>, <c>best_version</c>, <c>portageq</c> + </dt> + <dd> + <p> + Calls to any of these globally indicates a serious problem. You must <b>not</b> + have metadata varying based upon system-dependent information <d/> see `The + Portage Cache`_. You should rewrite your ebuilds to correctly use + dependencies. + </p> + </dd> + <dt> + <c>python</c>, <c>perl</c> etc + </dt> + <dd> + <p> + Ebuilds are <c>bash</c> scripts. Offloading anything you don't know how to do + in <c>bash</c> onto another language is not acceptable <d/> if nothing else, + because not all users will always have a full system when ebuilds are + sourced. + </p> + </dd> +</dl> + +</body> +</subsection> + +<subsection> +<title>QA Notice <d/> foo is setXid, dynamically linked and using lazy bindings</title> +<body> + +<p> +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: +</p> + +<ul> + <li> + Modify the package's Makefile (or equivalent) to use <c>-Wl,-z,now</c> when + linking. This solution is preferred. + </li> + <li> + Use <c>append-ldflags</c> (see `Adding Additional Flags`_) to add <c>-Wl,-z,now</c>. + This will affect <e>all</e> binaries installed, not just the setXid ones. + </li> +</ul> + +</body> +</subsection> + +<subsection> +<title>QA Notice <d/> ECLASS foo inherited illegally</title> +<body> + +<p> +All eclass inherits must be unconditional, or based purely upon static +machine-independent criteria (<c>PN</c> and <c>PV</c> are most common here). See `The +Portage Cache`_. +</p> + +<p> +You may see this warning in situations where there is not actually any illegal +inheritance occurring. Most commonly: +</p> + +<ul> + <li> + When unmerging a package which was installed using an old portage version that + did not record inheritance. + </li> + <li> + When working with eclasses in an overlay with a stale cache. See `Overlay and + Eclasses`_. + </li> + <li> + When working with a stale portage cache. + </li> +</ul> + +<p> +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 +<c>emerge sync</c> over <c>rsync</c> setup, it is probably a genuine issue. +</p> + +</body> +</subsection> + +<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 +</todo> + +</body> +</section> + +<section> +<title>Handling <c>repoman</c> Messages</title> +<body> + +<todo> +write me +</todo> + +</body> +</section> + +<section> +<title>Handling Access Violations</title> +<body> + +<p> +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. +</p> + +<p> +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): :: +</p> + +<pre> + --------------------------- ACCESS VIOLATION SUMMARY --------------------------- + LOG FILE = "/tmp/sandbox-app-misc_-_breakme-1-31742.log" + + open_wr: /big-fat-red-error + -------------------------------------------------------------------------------- +</pre> + +<p> +The <c>open_wr</c> 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 +<c>/big-fat-red-error</c>. +</p> + +<p> +Other error messages exist for read-restricted areas <d/> these are rarely used in +ebuilds. +</p> + +<p> +Access violations most commonly occur during the install phase. See +<c>src_install</c> and `Install Destinations`_ for discussion. +</p> + +<p> +Sometimes problems can also occur with packages attempting to write to +<c>${HOME}</c>. To get around this, it is usually sufficient to trick the build +system into using a safer location. For example, the <c>fluxbox</c> menu generator +tries to work in <c>${HOME}/.fluxbox</c> <d/> to get around this, the following is +used: +</p> + +<codesample lang="ebuild"> +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 $? +</codesample> + +<p> +In this situation, providing a fake home directory is all that is needed. +</p> + +</body> +</section> + +</body> +</chapter> +</guide> |