Mercurial > hg > aboriginal
changeset 1225:39fda120621c
Fluff out the debugging section of the FAQ a bit more, explaining EXTRACT_ALL and NO_SANITIZE_ENVIRONMENT.
author | Rob Landley <rob@landley.net> |
---|---|
date | Mon, 23 Aug 2010 00:28:41 -0500 |
parents | f0d7f84ec51a |
children | b72a5e74833f |
files | www/FAQ.html |
diffstat | 1 files changed, 46 insertions(+), 13 deletions(-) [+] |
line wrap: on
line diff
--- a/www/FAQ.html Mon Aug 23 00:27:44 2010 -0500 +++ b/www/FAQ.html Mon Aug 23 00:28:41 2010 -0500 @@ -17,7 +17,10 @@ <li><p><a href=#package_breaks>Q: Why did package build $NAME die because it couldn't find $PREREQUISITE, even though it's installed?</a></p></li> -<li><p><a href=#debugging>Q: It broke! How do I debug it?</a></p></li> +<li><p><a href=#environment_sanitizing>Q: Why isn't the build listening to the environment variables I set?</p></li> + +<li><p><a href=#debugging><h1>Debugging questions</h1></a></p></li> + <ul> <li><p><a href=#debug_logging>Q: How do I get better log output?</p></li> <li><p><a href=#debug_source>Q: How do I play around with package source code?</p></li> @@ -231,9 +234,20 @@ headers and libraries don't have, and that the target root filesystem may not have installed.</p> -<a name="debugging" /><h2>It broke! how do I debug it?</h2> +<a name=environment_sanitizing /><h2>Q: Why isn't the build listening to the environment variables I set?</h2> + +<p>Quick answer: export NO_SANITIZE_ENVIRONMENT=1.</p> -<a name="debug_logging" /><h2>Q: How do I get better log output from the build?</h2></li> +<p>Long answer: you probably deleted the commented out variables from "config" +and then tried to set them on the command line. The environment sanitizing +logic has a whitelist of variables, but also looks at config to see what +variables are exported in there (whether they're commented out or not) and +lets those through from the environment as well. If you remove them from +config, it won't let them through from the environment.</p> + +<a name="debugging" /><h1>Debugging questions</h1> + +<a name="debug_logging" /><h2>Q: How do I get better log output from the build?</h2> <h3><b>Get a verbose, single-processor log of the build output.</b></h3> @@ -307,16 +321,19 @@ <h3><b>Extracting and patching</b></h3> -<p>In theory the function "setupfor" extracts a tarball (from the -"packages" directory), patches it if necessary (applying all the files in -"sources/patches" that start with that package's name, which come from -the aboriginal linux repository), and cd's into the resulting directory. -Eventually the function "cleanup" does an "rm -rf" on that -directory when you're done. In practice, the infrastructure behind the -scenes implements a lot of optimizations to save disk space, CPU time, and I/O -bandwidth, which speeds up builds (especially when you do a lot of them -in parallel). This infrastructure is designed to be easily ignored, but -understanding it can be useful for debugging.</p> +<p>Each script to build a package calls the shell function "setupfor" +before building the package, and "cleanup" afterwards. Conceptually, +"setupfor" extracts a tarball (from the "packages" directory), +patches it if necessary (applying all the files in "sources/patches" that +start with that package's name, which come from the aboriginal linux +repository), and cd's into the resulting directory. The function "cleanup" +does an "rm -rf" on that directory when you're done.</p> + +<p>In practice, the infrastructure behind the scenes caches the extracted +tarballs. This optimization saves disk space, CPU time, and I/O bandwidth, +speeding up builds considerably (especially when you do a lot of them in +parallel). This optimization is designed to be easily ignored, but +understanding the infrastructure can be useful for debugging.</p> <p>There are two places to look for extracted source packages: the package cache and the working copy. The <b>package cache</b> (in "build/packages") @@ -402,6 +419,22 @@ zap the entire package cache, or just "rm -rf build" to clean up all the temporary files).</p> +<p>If the environment variable EXTRACT_ALL is set, download.sh will +call extract_package on each package as soon as it confirms the tarball's +sha1sum. (The environment variable FORK makes each package download happen +in parallel, including the call to extract_package if any.) Prepopulating +the package cache this way is useful before running different architecture +builds in parallel, or when testing that new patches (added to the +sources/patches directory) apply correctly to the relevant package(s).</p> + +<p>This means you can do the following to get a freshly extracted and patched +clean copy of all packages:</p> + +<blockquote><pre> + rm -rf build/packages + EXTRACT_ALL=1 ./download.sh +</pre></blockquote> + <a name=debug_working_copies /><h2>Q: What are working copies for?</p></h2> <p>Working copies are target-specific copies of package source where builds