[steeldump-cvs] r5 - trunk/steeldump-web
dlichteblau at common-lisp.net
dlichteblau at common-lisp.net
Sun May 28 14:27:44 UTC 2006
Author: dlichteblau
Date: Sun May 28 10:27:42 2006
New Revision: 5
Added:
trunk/steeldump-web/building.html
Modified:
trunk/steeldump-web/index.html
Log:
moved development instruction to their own page
added version numbers
Added: trunk/steeldump-web/building.html
==============================================================================
--- (empty file)
+++ trunk/steeldump-web/building.html Sun May 28 10:27:42 2006
@@ -0,0 +1,261 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+ <head>
+ <title>Steeldump</title>
+ <link rel="stylesheet" type="text/css" href="steeldump.css"/>
+ </head>
+ <body>
+ <div class="sidebar">
+ <div class="sidebar-title">
+ about steeldump
+ </div>
+ <div class="sidebar-main" style="padding-bottom: 1px">
+ <ul>
+ <li>
+ <a href="index.html">Main page:</a>
+ <ul class="sub">
+ <li><a href="index.html#installation">Installation</a></li>
+ <li><a href="index.html#usage">Usage</a></li>
+ <li><a href="index.html#bugs">How to report problems</a></li>
+ </ul>
+ Development:
+ <ul class="sub">
+ <li><a href="building.html">Building Steeldump</a></li>
+ <li><a href="#extending">Extending Steeldump</a></li>
+ </ul>
+ </li>
+ <li>
+ <a href="http://common-lisp.net/cgi-bin/mailman/listinfo/steeldump-devel">
+ steeldump-devel at common-lisp.net
+ </a>
+ </li>
+ <li>
+ <a href="http://common-lisp.net/websvn/listing.php?repname=steeldump&path=%2F&sc=0">
+ Browse SVN
+ </a>
+ </li>
+ </ul>
+ </div>
+ </div>
+
+ <h1>Steeldump<sub style="font-weight: normal; font-size: 10pt; color: #009c00">BETA</sub></h1>
+
+ <h3>
+ Building Steeldump
+ <a name="building"></a>
+ </h3>
+ <p>
+ (You can skip this section if you just want to use steeldump
+ packages normally. See above for installation instructions.)
+ </p>
+ <p>
+ To help debugging or developing Steeldump, the following steps
+ should be enough to build your own steeldump packages:
+ </p>
+ <ul>
+ <li>
+ Set up a chroot environment or virtual machine to compile
+ steeldump in.
+ <br/>
+ <br/>
+ If you really do not want to do this, keep this in mind:
+ Steeldump <i>must</i> be compiled in the exact same location
+ where it is going to be installed into,
+ <tt>/opt/steeldump</tt>. So you cannot run the steeldump
+ scripts in a filesystem where steeldump packages are already
+ installed.
+ <br/>
+ <br/>
+ Although it does not address safety issues, you can obviously
+ build a mock-up chroot very easily using <tt>mount -o bind</tt>,
+ so this should not be too much of an issue.
+ </li>
+ <li>
+ Create a new directory <tt>/opt/steeldump</tt>. In the build
+ environment, this directory should be owned by a non-root user.
+ (The build scripts will only run <tt>sudo</tt> briefly for each
+ package to fix file ownership before packaging the files up.
+ Building should be done normally under your non-root account.)
+ </li>
+ <li>
+ Check out the steeldump scripts from Subversion:
+ <pre>$ cd /opt/steeldump
+$ svn co svn://common-lisp.net/project/steeldump/svn/trunk/scripts</pre>
+ </li>
+ <li>
+ Run the first script:
+ <pre>/opt/steeldump$ ./scripts/init</pre>
+ -- or just look at what it does. It merely creates a few
+ directories and checks whether required software is installed.
+ CMUCL is used for building (you can use the debian-provided
+ cmucl package), and dpkg-dev tools as well as sudo are needed.
+ </li>
+ <li>
+ The first package you need to download and build is SBCL:
+ <pre>$ ./scripts/fetch-sbcl
+$ ./scripts/build-sbcl
+$ ./scripts/makedeb-sbcl</pre>
+ </li>
+ </ul>
+ <p>
+ Congratulations: If that worked, you have your first .deb package in
+ <tt>/opt/steeldump/pool</tt>.
+ </p>
+ <ul>
+ <li>
+ Now you can build the actual steeldumped applications using the
+ same steps:
+ <pre>$ ./scripts/fetch-all
+$ ./scripts/build-all
+$ ./scripts/makedeb-all</pre>
+ </li>
+ </ul>
+ <p>
+ And that's it. After makedeb-all, you can find all packages in
+ the <tt>pool</tt> directory.
+ </p>
+ <p>
+ While debugging, however, you will probably want to build
+ individual packages instead of all in one go:
+ </p>
+ <ul>
+ <li>
+ For every system, there is a separate <tt>fetch-</tt><i>foo</i>
+ script. These fetch-scripts do <i>not</i> track dependencies
+ for you. When not using <tt>fetch-all</tt>, make sure to
+ download everything you need before trying to build.
+ </li>
+ <li>
+ The <tt>build-</tt><i>foo</i> scripts can be invoked in an
+ arbitrary order. For example, building climacs will
+ automatically compile mcclim if it had not been compiled
+ yet. <i>However</i>, it does not actually create the dumpfile
+ for mcclim, you will still have to call <tt>build-mcclim</tt>
+ eventually before you can make its .deb file.
+ </li>
+ <li>
+ Finally, for <tt>makedeb-all</tt> note that it has one advantage
+ over the individual <tt>makedeb-</tt><i>foo</i> scripts: Before
+ calling out to the others, <tt>makedeb-all</tt> relocates the
+ heap files to non-overlapping locations, speeding up loading of
+ the heap files a little.
+ </li>
+ </ul>
+ <p>
+ If you got this far and have working packages in
+ <tt>/opt/steeldump/pool</tt>, send me a postcard.
+ </p>
+
+ <h3>
+ Extending Steeldump
+ <a name="extending"></a>
+ </h3>
+ <p>
+ (You can skip this section if you just want to use steeldump
+ packages normally. See above for installation instructions.)
+ </p>
+ <p>
+ To add a new package called "blubba", create these files:
+ </p>
+ <ul>
+ <li>
+ <tt>/opt/steeldump/scripts/fetch-blubba</tt><br/>
+ This script must put the source code into
+ <tt>/opt/steeldump/src/blubba</tt>. Remove version numbers from
+ the directory name, if any.<br/>
+ Look at the other fetch scripts for ideas. Usually it is enough
+ to call one of the helper scripts, <tt>aux/fetch-url</tt>,
+ <tt>aux/fetch-cvs</tt>, or <tt>aux/fetch-svn</tt>. If you have
+ to patch the source code, this script is the right place to do
+ that.
+ </li>
+ <li>
+ <tt>/opt/steeldump/scripts/build-blubba</tt><br/>
+ Usually this script is trivial and just
+ calls <tt>build-system</tt>. Copy
+ over <tt>/opt/steeldump/scripts/build-SAMPLE</tt> and change the
+ system name from "SAMPLESSYTEMNAME" to "blubba". This script
+ is the right place to call "make" if the system includes C code.
+ </li>
+ <li>
+ <tt>/opt/steeldump/scripts/lisp/build-blubba.lisp</tt><br/>
+ This Lisp script is less trivial. Starting from the sample file
+ <tt>/opt/steeldump/scripts/lisp/build-SAMPLE.lisp</tt>, change
+ the system name from "SAMPLE" to "blubba", but review the
+ heap dumping logic carefully. The heap dumper needs to be told
+ about:
+ <ul>
+ <li>
+ The packages that are to be dumped (look out for multiple
+ defpackage forms). This is the first argument
+ to <tt>dump-system</tt>.
+ </li>
+ <li>
+ The ASDF systems involved. If the .asd file contains
+ multiple system definitions, all of them must be listed
+ manually in the build script. (The <tt>:system</tt>
+ argument.)
+ </li>
+ <li>
+ The name of the package the .asd files defines and uses.
+ (The <tt>:system-package</tt> argument.)
+ </li>
+ </ul>
+ You now have a first draft of the dumping script. Beware that
+ <em>dumping</em> is not the part where things tend to fail, it is the
+ loading and running of heap files where mistakes show up. The
+ heuristic used by the heapdumper is that it thinks in terms of
+ packages. For many systems, you will have to supply more
+ information than just the package names, because the software
+ often installs objects into variables contained
+ in <em>other</em> packages, slots of objects the heap dumper
+ cannot know about, etc.
+ <ul>
+ <li>
+ Refer to sb-heapdump documentation on the precise logic used
+ by the dumper.
+ </li>
+ <li>
+ For CLIM systems in particular, application-defined command
+ tables and presentation types need to be extracted from
+ McCLIM-internal tables. CLIM also has methods that are
+ eql-specializing on objects like +flipping-ink+, so we must
+ guarantee uniqueness of these objects. For details, see
+ the build scripts for gsharp and climacs.
+ </li>
+ <li>
+ Any CLOS usage can be tricky. The heap dumper will (a)
+ include generic functions and all their methods in the
+ package the generic function's name is in (for example, the
+ MCCLIM package), and (b) additional methods in a different
+ package if those methods specialize on a class named by a
+ symbol in that other package (for example, methods defined
+ for classes in the CLIMACS package). One corollary of these
+ rules is that we must not dump the McCLIM package after
+ having loaded Climacs into the same core, because then
+ loading of McCLIM would fail trying to find the CLIMACS
+ package.
+ </li>
+ </ul>
+ </li>
+ <li>
+ <tt>/opt/steeldump/scripts/descriptions/blubba</tt><br/>
+ This file ends up as the <tt>Description:</tt> header in the
+ Debian package's <tt>control</tt> file.
+ Again there is a skeleton file:
+ <tt>/opt/steeldump/scripts/descriptions/SAMPLE</tt>.
+ </li>
+ <li>
+ <tt>/opt/steeldump/scripts/makedeb-blubba</tt><br/>
+ This scripts collect all files to be installed and creates the
+ .deb archive. Starting
+ with <tt>/opt/steeldump/scripts/makedeb-SAMPLE</tt>,
+ replace SAMPLESYSTEMNAME with "blubba", and DEPENDENCIES with other
+ steeldump packages that "blubba" depends on. Omit the
+ "steeldump-" prefix and version number, the helper script
+ inserts those for you.
+ </li>
+ </ul>
+ </body>
+</html>
Modified: trunk/steeldump-web/index.html
==============================================================================
--- trunk/steeldump-web/index.html (original)
+++ trunk/steeldump-web/index.html Sun May 28 10:27:42 2006
@@ -18,8 +18,11 @@
<li><a href="#installation">Installation</a></li>
<li><a href="#usage">Usage</a></li>
<li><a href="#bugs">How to report problems</a></li>
- <li><a href="#building">Building Steeldump</a></li>
- <li><a href="#extending">Extending Steeldump</a></li>
+ </ul>
+ Development:
+ <ul class="sub">
+ <li><a href="building.html">Building Steeldump</a></li>
+ <li><a href="building.html#extending">Extending Steeldump</a></li>
</ul>
</li>
<li>
@@ -39,9 +42,18 @@
</div>
<div class="sidebar-main">
<ul>
- <li><a href="http://common-lisp.net/project/beirc">beirc</a></li>
- <li><a href="http://common-lisp.net/project/climacs">climacs</a></li>
- <li><a href="http://common-lisp.net/project/gsharp">gsharp</a></li>
+ <li>
+ <a href="http://common-lisp.net/project/beirc">beirc</a>
+ <sub> from CVS</sub>
+ </li>
+ <li>
+ <a href="http://common-lisp.net/project/climacs">climacs</a>
+ <sub> from CVS</sub>
+ </li>
+ <li>
+ <a href="http://common-lisp.net/project/gsharp">gsharp</a>
+ <sub> from CVS</sub>
+ </li>
</ul>
</div>
<div class="sidebar-title">
@@ -49,22 +61,55 @@
</div>
<div class="sidebar-main">
<ul>
- <li><a href="http://weitz.de/cl-fad/">cl-fad</a></li>
- <li><a href="http://common-lisp.net/project/cl-irc">cl-irc</a></li>
- <li><a href="http://weitz.de/cl-ppcre/">cl-ppcre</a></li>
+ <li>
+ <a href="http://weitz.de/cl-fad/">cl-fad</a>
+ <sub> 0.5.0</sub>
+ </li>
+ <li>
+ <a href="http://common-lisp.net/project/cl-irc">cl-irc</a>
+ <sub> from SVN</sub>
+ </li>
+ <li>
+ <a href="http://weitz.de/cl-ppcre/">cl-ppcre</a>
+ <sub> 1.2.14</sub>
+ </li>
<li>
<a href="http://common-lisp.net/project/climacs">esa</a>
+ <sub> from CVS</sub>
(<a href="http://www.cliki.net/esa">about</a>)
</li>
- <li><a href="http://www.cliki.net/CLX">clx</a></li>
- <li><a href="http://weitz.de/flexi-streams/">flexi-streams</a></li>
- <li><a href="http://common-lisp.net/project/flexichain">flexichain</a></li>
- <li><a href="http://common-lisp.net/project/mcclim">McCLIM</a></li>
- <li><a href="http://www.cliki.net/spatial-trees">spatial-trees</a></li>
- <li><a href="http://www.cliki.net/split-sequence">split-sequence</a></li>
+ <li>
+ <a href="http://www.cliki.net/CLX">clx</a>
+ <sub> 0.7.3</sub>
+ </li>
+ <li>
+ <a href="http://weitz.de/flexi-streams/">flexi-streams</a>
+ <sub> 0.5.5</sub>
+ </li>
+ <li>
+ <a href="http://common-lisp.net/project/flexichain">flexichain</a>
+ <sub> from CVS</sub>
+ </li>
+ <li>
+ <a href="http://common-lisp.net/project/mcclim">McCLIM</a>
+ <sub> from CVS</sub>
+ </li>
+ <li>
+ <a href="http://www.cliki.net/spatial-trees">spatial-trees</a>
+ <sub> 0.2</sub>
+ </li>
+ <li>
+ <a href="http://www.cliki.net/split-sequence">split-sequence</a>
+ </li>
<li>tab-layout</li>
- <li><a href="http://common-lisp.net/project/cl-plus-ssl#trivial-gray-streams">trivial-gray-streams</a></li>
- <li><a href="http://www.cliki.net/trivial-sockets">trivial-sockets</a></li>
+ <li>
+ <a href="http://common-lisp.net/project/cl-plus-ssl#trivial-gray-streams">trivial-gray-streams</a>
+ <sub> from CVS</sub>
+ </li>
+ <li>
+ <a href="http://www.cliki.net/trivial-sockets">trivial-sockets</a>
+ <sub> 0.3</sub>
+ </li>
</ul>
</div>
</div>
@@ -204,222 +249,5 @@
If, however, the bug is also present is the upstream source code,
please send your report directly to the upstream project. Thanks.
</p>
-
- <h3>
- Building Steeldump
- <a name="building"></a>
- </h3>
- <p>
- (You can skip this section if you just want to use steeldump
- packages normally. See above for installation instructions.)
- </p>
- <p>
- To help debugging or developing Steeldump, the following steps
- should be enough to build your own steeldump packages:
- </p>
- <ul>
- <li>
- Set up a chroot environment or virtual machine to compile
- steeldump in.
- <br/>
- <br/>
- If you really do not want to do this, keep this in mind:
- Steeldump <i>must</i> be compiled in the exact same location
- where it is going to be installed into,
- <tt>/opt/steeldump</tt>. So you cannot run the steeldump
- scripts in a filesystem where steeldump packages are already
- installed.
- <br/>
- <br/>
- Although it does not address safety issues, you can obviously
- build a mock-up chroot very easily using <tt>mount -o bind</tt>,
- so this should not be too much of an issue.
- </li>
- <li>
- Create a new directory <tt>/opt/steeldump</tt>. In the build
- environment, this directory should be owned by a non-root user.
- (The build scripts will only run <tt>sudo</tt> briefly for each
- package to fix file ownership before packaging the files up.
- Building should be done normally under your non-root account.)
- </li>
- <li>
- Check out the steeldump scripts from Subversion:
- <pre>$ cd /opt/steeldump
-$ svn co svn://common-lisp.net/project/steeldump/svn/trunk/scripts</pre>
- </li>
- <li>
- Run the first script:
- <pre>/opt/steeldump$ ./scripts/init</pre>
- -- or just look at what it does. It merely creates a few
- directories and checks whether required software is installed.
- CMUCL is used for building (you can use the debian-provided
- cmucl package), and dpkg-dev tools as well as sudo are needed.
- </li>
- <li>
- The first package you need to download and build is SBCL:
- <pre>$ ./scripts/fetch-sbcl
-$ ./scripts/build-sbcl
-$ ./scripts/makedeb-sbcl</pre>
- </li>
- </ul>
- <p>
- Congratulations: If that worked, you have your first .deb package in
- <tt>/opt/steeldump/pool</tt>.
- </p>
- <ul>
- <li>
- Now you can build the actual steeldumped applications using the
- same steps:
- <pre>$ ./scripts/fetch-all
-$ ./scripts/build-all
-$ ./scripts/makedeb-all</pre>
- </li>
- </ul>
- <p>
- And that's it. After makedeb-all, you can find all packages in
- the <tt>pool</tt> directory.
- </p>
- <p>
- While debugging, however, you will probably want to build
- individual packages instead of all in one go:
- </p>
- <ul>
- <li>
- For every system, there is a separate <tt>fetch-</tt><i>foo</i>
- script. These fetch-scripts do <i>not</i> track dependencies
- for you. When not using <tt>fetch-all</tt>, make sure to
- download everything you need before trying to build.
- </li>
- <li>
- The <tt>build-</tt><i>foo</i> scripts can be invoked in an
- arbitrary order. For example, building climacs will
- automatically compile mcclim if it had not been compiled
- yet. <i>However</i>, it does not actually create the dumpfile
- for mcclim, you will still have to call <tt>build-mcclim</tt>
- eventually before you can make its .deb file.
- </li>
- <li>
- Finally, for <tt>makedeb-all</tt> note that it has one advantage
- over the individual <tt>makedeb-</tt><i>foo</i> scripts: Before
- calling out to the others, <tt>makedeb-all</tt> relocates the
- heap files to non-overlapping locations, speeding up loading of
- the heap files a little.
- </li>
- </ul>
- <p>
- If you got this far and have working packages in
- <tt>/opt/steeldump/pool</tt>, send me a postcard.
- </p>
-
- <h3>
- Extending Steeldump
- <a name="extending"></a>
- </h3>
- <p>
- (You can skip this section if you just want to use steeldump
- packages normally. See above for installation instructions.)
- </p>
- <p>
- To add a new package called "blubba", create these files:
- </p>
- <ul>
- <li>
- <tt>/opt/steeldump/scripts/fetch-blubba</tt><br/>
- This script must put the source code into
- <tt>/opt/steeldump/src/blubba</tt>. Remove version numbers from
- the directory name, if any.<br/>
- Look at the other fetch scripts for ideas. Usually it is enough
- to call one of the helper scripts, <tt>aux/fetch-url</tt>,
- <tt>aux/fetch-cvs</tt>, or <tt>aux/fetch-svn</tt>. If you have
- to patch the source code, this script is the right place to do
- that.
- </li>
- <li>
- <tt>/opt/steeldump/scripts/build-blubba</tt><br/>
- Usually this script is trivial and just
- calls <tt>build-system</tt>. Copy
- over <tt>/opt/steeldump/scripts/build-SAMPLE</tt> and change the
- system name from "SAMPLESSYTEMNAME" to "blubba". This script
- is the right place to call "make" if the system includes C code.
- </li>
- <li>
- <tt>/opt/steeldump/scripts/lisp/build-blubba.lisp</tt><br/>
- This Lisp script is less trivial. Starting from the sample file
- <tt>/opt/steeldump/scripts/lisp/build-SAMPLE.lisp</tt>, change
- the system name from "SAMPLE" to "blubba", but review the
- heap dumping logic carefully. The heap dumper needs to be told
- about:
- <ul>
- <li>
- The packages that are to be dumped (look out for multiple
- defpackage forms). This is the first argument
- to <tt>dump-system</tt>.
- </li>
- <li>
- The ASDF systems involved. If the .asd file contains
- multiple system definitions, all of them must be listed
- manually in the build script. (The <tt>:system</tt>
- argument.)
- </li>
- <li>
- The name of the package the .asd files defines and uses.
- (The <tt>:system-package</tt> argument.)
- </li>
- </ul>
- You now have a first draft of the dumping script. Beware that
- <em>dumping</em> is not the part where things tend to fail, it is the
- loading and running of heap files where mistakes show up. The
- heuristic used by the heapdumper is that it thinks in terms of
- packages. For many systems, you will have to supply more
- information than just the package names, because the software
- often installs objects into variables contained
- in <em>other</em> packages, slots of objects the heap dumper
- cannot know about, etc.
- <ul>
- <li>
- Refer to sb-heapdump documentation on the precise logic used
- by the dumper.
- </li>
- <li>
- For CLIM systems in particular, application-defined command
- tables and presentation types need to be extracted from
- McCLIM-internal tables. CLIM also has methods that are
- eql-specializing on objects like +flipping-ink+, so we must
- guarantee uniqueness of these objects. For details, see
- the build scripts for gsharp and climacs.
- </li>
- <li>
- Any CLOS usage can be tricky. The heap dumper will (a)
- include generic functions and all their methods in the
- package the generic function's name is in (for example, the
- MCCLIM package), and (b) additional methods in a different
- package if those methods specialize on a class named by a
- symbol in that other package (for example, methods defined
- for classes in the CLIMACS package). One corollary of these
- rules is that we must not dump the McCLIM package after
- having loaded Climacs into the same core, because then
- loading of McCLIM would fail trying to find the CLIMACS
- package.
- </li>
- </ul>
- </li>
- <li>
- <tt>/opt/steeldump/scripts/descriptions/blubba</tt><br/>
- This file ends up as the <tt>Description:</tt> header in the
- Debian package's <tt>control</tt> file.
- Again there is a skeleton file:
- <tt>/opt/steeldump/scripts/descriptions/SAMPLE</tt>.
- </li>
- <li>
- <tt>/opt/steeldump/scripts/makedeb-blubba</tt><br/>
- This scripts collect all files to be installed and creates the
- .deb archive. Starting
- with <tt>/opt/steeldump/scripts/makedeb-SAMPLE</tt>,
- replace SAMPLESYSTEMNAME with "blubba", and DEPENDENCIES with other
- steeldump packages that "blubba" depends on. Omit the
- "steeldump-" prefix and version number, the helper script
- inserts those for you.
- </li>
- </ul>
</body>
</html>
More information about the Steeldump-cvs
mailing list