Docs diffs
Adriaan de Groot <adridg-FlD2LfDziEhmR6Xm/[email protected]>
| Newsgroups | gmane.comp.tools.aap.devel |
|---|---|
| Message-ID | <[email protected]> |
Several attached diffs:
* tech.diff fixes ref-attributes.sgml, which used lots of   entities (note
missing semicolon) and had an unbalanced tgroup.
* install.diff is a pretty substantial rewrite of user-install.sgml. It tries
to collapse a table and a programlisting into one, while adding explanations.
One sentence in the original mystifies me:
All these dependencies that &Aap; adds are at the toplevel (unlike "clean"
and "cleanmore", which are done for each parent and child recipe).
why (or how) is this relevant? Can you notice this at all as an AAP user?
I've gone and used <replaceable> here and there - I don't think the tag
appears anywhere else in the docs till now. I'd also like to mark up some
parts with <note> or <warning>, and this reminds me that only Bram knows what
the markup conventions are, and it's hard to follow rules that aren't written
down. As a random start to documenting the markup style:
* exec.diff adds a comment showing some of the markup conventions, as near as
I understand them.
* tutor-distribute.diff shortens the tutorial on uploading a little - but
perhaps there was a special reason to use :include and do some weirdness in
the original example there?
I'm rather inclined to swap "distributing a program" and "publishing a
website", and moving the description of {publish} to the "distributing a
program" part. Then "compiling" and "distributing" are fairly generic and
abstract, while "publishing" puts them to use for a concrete case (one that's
pretty neat as well).
Would it make sense to index the tutorial some? There's lots of little notes
and tips and tricks in there that you can never find except by reading the
whole thing (stuff about indentation, $TOPDIR, comes to mind).
--
pub 1024D/FEA2A3FE 2002-06-18 Adriaan de Groot <[email protected]>
Key fingerprint = 934E 31AA 80A7 723F 54F9 50ED 76AC EE01 FEA2 A3FE
tech.diff
(text/x-diff, 2 KB)
diff -u doc/ref-attributes.sgml doc-new/ref-attributes.sgml
--- doc/ref-attributes.sgml Tue Aug 19 11:58:55 2003
+++ doc-new/ref-attributes.sgml Wed Aug 20 20:33:57 2003
@@ -77,7 +77,7 @@
<entry>remove all generated files, AAPDIR and build-*
directories below the toplevel recipe</entry>
</row><row>
- <entry> </entry><entry> </entry>
+ <entry> </entry><entry> </entry>
</row><row>
<entry>test</entry>
@@ -95,13 +95,13 @@
<entry>tryout</entry>
<entry>build and install for trying out</entry>
</row><row>
- <entry> </entry><entry> </entry>
+ <entry> </entry><entry> </entry>
</row><row>
<entry>reference </entry>
<entry>generate or update the cross-reference database</entry>
</row><row>
- <entry> </entry><entry> </entry>
+ <entry> </entry><entry> </entry>
</row><row>
<entry>fetch</entry>
@@ -110,7 +110,7 @@
<entry>update</entry>
<entry>fetch and build the default targets</entry>
</row><row>
- <entry> </entry><entry> </entry>
+ <entry> </entry><entry> </entry>
</row><row>
<entry>checkout</entry>
@@ -137,7 +137,7 @@
<entry>tag</entry>
<entry>add a tag to the current version</entry>
</row><row>
- <entry> </entry><entry> </entry>
+ <entry> </entry><entry> </entry>
</row><row>
<entry>prepare</entry>
@@ -146,13 +146,14 @@
<entry>publish</entry>
<entry>distribute all files for the current version</entry>
</row><row>
- <entry> </entry><entry> </entry>
+ <entry> </entry><entry> </entry>
</row><row>
<entry>finally</entry>
<entry>always executed last (using "aap finally" is uncommon)</entry>
</row>
</tbody>
+ </tgroup>
</table>
</para>
install.diff
(text/x-diff, 11.5 KB)
--- doc/user-install.sgml Wed Aug 20 07:35:56 2003
+++ doc-new/user-install.sgml Fri Aug 22 11:10:29 2003
@@ -9,62 +9,215 @@
-->
<para>
-This is about installing the produced programs and other items.
+This section contains details about the installation
+of the produced programs and other items.
+Those other items can be libraries (produced by the
+<link linkend="cmd-lib"><literal>:lib</literal></link>,
+<link linkend="cmd-dll"><literal>:dll</literal></link>,
+or
+<link linkend="cmd-ltlib"><literal>:ltlib</literal></link>
+commands),
+header files for the API of a library,
+documentation (like manpages or info files),
+and as a catch-all, "data."
</para>
+
+
+
+<para>
+Usually installing is done with
+<userinput>aap install</userinput>.
+If you do not define an
+"install" target in the recipe, &Aap; will add one for you.
+The default install target invokes up to 15 other install
+targets, one for each kind of item you can install.
+This makes it easy to customize the installation of
+some particular kind of item (e.g. libtool archives).
+</para>
+
+
<para>
-Usually installing is done with "aap install". When you did not define an
-"install" target in the recipe, Aap will add one for you. This default
+The default
install target invokes two or three other targets:
-<informaltable frame="none">
- <tgroup cols="2">
- <colspec colwidth='2.0in'/><!--/-->
+install-platform, install-shared, and (optionally,
+only if you define it in the recipe) install-local.
+Each of these invokes other install targets for
+specific kinds of files, as follows:
+</para>
+
+<table frame="none" id="tbl-install">
+ <title>Install targets</title>
+ <tgroup cols="3">
+ <colspec colwidth='2.0in,2.0in,4.0in'/><!--/-->
+ <thead>
+ <row>
+ <entry>High-level Target</entry>
+ <entry>Lower-level Targets</entry>
+ <entry>Install these Files</entry>
+ </row>
+ </thead>
+
<tbody>
<row>
<entry>install-platform</entry>
- <entry>this is for installing platform-dependent files</entry>
+ <entry> </entry>
+ <entry>This is for installing platform-dependent files.</entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-platform -->
+ <entry>install-exec</entry>
+ <entry><para>Install programs (generally produced through
+ <link linkend="cmd-program"><literal>:program</literal></link>
+ command).
+ </para></entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-platform -->
+ <entry>install-sbin</entry>
+ <entry>Install programs for system administration.
+ These
+ may have additional security considerations, hence a separate target.
+ </entry>
</row>
+
+ <row>
+ <entry> </entry><!-- under install-platform -->
+ <entry>install-lib</entry>
+ <entry>Install static libraries (from the
+ <link linkend="cmd-lib"><literal>:lib</literal></link> command).
+ </entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-platform -->
+ <entry>install-dll</entry>
+ <entry>Install shared libraries (from the
+ <link linkend="cmd-dll"><literal>:dll</literal></link> command).
+ </entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-platform -->
+ <entry>install-ltlib</entry>
+ <entry>
+ <para>Install shared libtool libraries (from the
+ <link linkend="cmd-ltlib"><literal>:ltlib</literal></link> command).
+ These require special treatment by the libtool program,
+ hence a separate target.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-platform -->
+ <entry>install-conf</entry>
+ <entry>Install platform-specific configuration files
+ (such as pkg-config files).
+ </entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-platform -->
+ <entry>install-platform-local</entry>
+ <entry>A catch-all for things that don't
+ fit anywhere else.
+ </entry>
+ </row>
+
<row>
<entry>install-shared</entry>
- <entry>this is for installing files shared between platforms</entry>
+ <entry> </entry>
+ <entry>This is for installing files shared between platforms.</entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-shared -->
+ <entry>install-data</entry>
+ <entry>Install data for the package.
+ This would typically include translation files,
+ examples (if they're not in the manpage),
+ and images used by the package.
+ </entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-shared -->
+ <entry>install-man</entry>
+ <entry>Install manpages.</entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-shared -->
+ <entry>install-info</entry>
+ <entry>Install GNU-style info pages.</entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-shared -->
+ <entry>install-include</entry>
+ <entry>Installs header files (also known as includes).
+ </entry>
+ </row>
+
+ <row>
+ <entry> </entry><!-- under install-shared -->
+ <entry>install-shared-local</entry>
+ <entry>A catch-all for things that don't fit anywhere else.</entry>
</row>
+
+
<row>
<entry>install-local</entry>
- <entry>this is an optional target that you can define for extra
- installing, without changing the other install targets.</entry>
+ <entry> </entry>
+ <entry><para>this is an optional target that you can define for extra
+ installing, without changing the other install targets.</para></entry>
</row>
</tbody>
</tgroup>
-</informaltable>
-To make it possible for you to specify which files are to be installed and how
-this happens, the dependencies are further split up:
-</para>
-<programlisting>
- install-platform : install-exec
- install-sbin
- install-lib
- install-dll
- install-conf
- install-platform-local
- install-shared : install-data
- install-man
- install-info
- install-include
- install-shared-local
-</programlisting>
+</table>
+
+
<para>
Each of these dependencies is only added automatically if you do not define
it yourself. In other words, if you do not define a dependency with
<computeroutput>install-data</computeroutput> as a target, &Aap; will add such a
dependency internally.
+ Unless you need special processing for specific kinds of items,
+ you should rarely need to define any of the install
+ targets yourself.
+ The exceptions are
+ <computeroutput>install-platform-local</computeroutput>,
+ <computeroutput>install-shared-local</computeroutput> and
+ <computeroutput>install-local</computeroutput>,
+ which you can define without disturbing &Aap;'s normal
+ mechanisms for installing the programs and libraries you create.
+</para>
+
+<para>
All these dependencies that &Aap; adds are at the toplevel (unlike "clean"
and "cleanmore", which are done for each parent and child recipe).
- "install-platform-local" and "install-shared-local" are optional, they are
- not added automatically.
</para>
+
+
<para>
-These variables are used:
+All of &Aap;'s default install targets operate in
+roughly the same fashion:
+specific actions are invoked for each install target.
+The default actions all use
+top-level variables
+named <literal>INSTALL_<replaceable>target</replaceable></literal>
+which collect filenames to install.
+Other toplevel variables control where those
+files are installed (<literal><replaceable>target</replaceable>DIR</literal>)
+and what file mode is used (<literal><replaceable>target</replaceable>MODE</literal>).
+This table shows the specific settings for each of
+the default install targets:
+</para>
+
<table frame="none">
- <title>Variables used for the install target</title>
+ <title>Settings for the install target</title>
<tgroup cols="7">
<thead>
<row>
@@ -72,9 +225,9 @@
<entry>variable</entry>
<entry>action</entry>
<entry>directory</entry>
- <entry>default</entry>
+ <entry>default directory</entry>
<entry>mode</entry>
- <entry>default</entry>
+ <entry>default mode</entry>
</row>
</thead>
<tbody>
@@ -114,6 +267,16 @@
<entry>$DLLMODE</entry>
<entry>0755</entry>
</row>
+
+ <row>
+ <entry>install-ltlib</entry>
+ <entry>$INSTALL_LTLIB</entry>
+ <entry span="5">
+ No default settings for libtool libraries have been
+ added to &Aap; yes. It seems likely that DLLDIR and DLLMODE will be used.
+ </entry>
+ </row>
+
<row>
<entry>install-conf</entry>
<entry>$INSTALL_CONF</entry>
@@ -175,37 +338,7 @@
</tbody>
</tgroup>
</table>
-</para>
-<para>
-If this is not sufficient and you do want to keep the defaults, you can add a
-dependency to do something extra:
-<informaltable frame="none">
- <tgroup cols="2">
- <colspec colwidth='2.0in'/><!--/-->
- <thead>
- <row>
- <entry>target</entry>
- <entry>invoked at the end of</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>install-local</entry>
- <entry>install</entry>
- </row>
- <row>
- <entry>install-platform-local</entry>
- <entry>install-platform</entry>
- </row>
- <row>
- <entry>install-shared-local</entry>
- <entry>install-shared</entry>
- </row>
- </tbody>
- </tgroup>
-</informaltable>
-</para>
<para>
The
@@ -214,6 +347,8 @@
<link linkend="cmd-lib">:lib</link> command adds its target to the $INSTALL_LIB variable.
The
<link linkend="cmd-dll">:dll</link> command adds its target to the $INSTALL_DLL variable.
+ The
+ <link linkend="cmd-ltlib">:ltlib</link> command adds its target to the $INSTALL_LTLIB variable.
</para>
<para>
The "installexec" action will strip the program by default, if the "strip"
@@ -275,6 +410,30 @@
<programlisting>
INSTALL_INCLUDE += sys/myheader.h {keepdir}
</programlisting>
+
+<para>
+As an alternative to {keepdir},
+there is the {installdir} attribute,
+which explicitly sets the relative path of the file to be installed.
+Files with an {installdir} attribute are
+installed in
+<literal>$DESTDIR$PREFIX$<replaceable>target</replaceable>DIR$installdir</literal>.
+The above setting could also be done as:
+<programlisting>
+ INSTALL_INCLUDE += sys/myheader.h {installdir=sys}
+</programlisting>
+The advantage of {installdir} over {keepdir} is that
+the relative paths (from toplevel recipe to file and from
+install directory to the desired install location)
+need not be the same.
+For instance:
+<programlisting>
+ INSTALL_INCLUDE += api/2.2/c/myheader.h {installdir=sys}
+</programlisting>
+</para>
+
+
+
<para>
The above mentioned mode variable is used to set the mode bits of the file
after installing. If this is not wanted, use the {keepmode} attribute.
@@ -313,7 +472,7 @@
If you hard code the paths from the parent to the files to install,
say by writing <literal>INSTALL_DATA += child/myscript.sh</literal>,
then you cannot execute the child recipe by itself (as if it were
-a toplevel recipe), since the paths will be wrong.
+a toplevel recipe), since the paths will be wrong.
Using <literal>$TOPDIR</literal>, or equivalently
the <literal>topdir</literal> function, is the safe way to do so.
</para>
exec.diff
(text/x-diff, 807 B)
--- doc/exec.sgml Fri Aug 22 09:55:22 2003 +++ doc-new/exec.sgml Fri Aug 22 12:28:29 2003 @@ -10,6 +10,25 @@ --> +<!-- Tagging conventions + +This table tries to map semantics to docbook tags. + +* Filenames and paths get <filename> +* Shell commands get <command> when mentioned +* Shell commands in running text for the user to enter just get <userinput> +* AAP commands when mentioned (:program) get <link linkend="cmd-..."> [<literal> too?] +* AAP commands as examples in running text (command ":do compile $source") + get double quotes " +* Variable names get $, no markup + +Some more conventions: + +* Program listings are indented 4 spaces and line-numbered (if needed) + with just numbers (no dots). + +--> + <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx.dtd" [
tutor-distribute.diff
(text/x-diff, 3.3 KB)
--- doc/tutor-distribute.sgml Wed Aug 20 07:35:34 2003
+++ doc-new/tutor-distribute.sgml Fri Aug 22 12:30:01 2003
@@ -15,6 +15,7 @@
</para>
+
<bridgehead>Downloading</bridgehead>
<para>
@@ -79,27 +80,31 @@
</para>
<para>
-A user of your program stores this recipe as "main.aap" and runs
+A user of your program stores this recipe as <filename>main.aap</filename> and runs
<userinput>aap</userinput> without arguments. What will happen is:
<orderedlist>
<listitem>
<para>
- Dependencies will be created for the <literal>:program</literal> command.
- to build "theprog" from "main.c" and "version.c".
+ Dependencies will be created by the <literal>:program</literal> command
+ to build "theprog" from
+ <filename>main.c</filename> and <filename>version.c</filename>.
</para>
</listitem>
<listitem>
<para>
- The target "theprog" depends on "main.c" and "version.c". Since these
+ The target "theprog" depends on
+ <filename>main.c</filename> and <filename>version.c</filename>.
+ Since these
files do not exist and they do have a <literal>fetch</literal> attribute, they
are fetched.
</para>
</listitem>
<listitem>
<para>
- The "main.c" file is inspected for dependencies. It includes the
- "common.h" file, which is automatically added to the list of dependencies.
- Since "common.h" does not exist and has a <literal>fetch</literal> attribute, it
+ The <filename>main.c</filename> file is inspected for dependencies. It includes the
+ <filename>common.h</filename> file, which is automatically
+ added to the list of dependencies.
+ Since <filename>common.h</filename> does not exist and has a <literal>fetch</literal> attribute, it
is fetched as well.
</para>
</listitem>
@@ -118,31 +123,20 @@
<para>
You need to upload the files mentioned in the recipe above. This needs to be
repeated each time one of the files changes. This is essentially the same as
-publishing a web site. This recipe will do the work:
+publishing a web site.
+You will need to upload both the source files and the recipe itself.
+The {publish} attribute can be used for this.
+You can add the following
+two lines to the recipe above in order to upload all the files:
</para>
<programlisting>
- :include main.aap
-
URL = scp://[email protected]//pub/theprog/%file%
:attr {publish = $URL} $Source $Header main.aap
-
- all: publish
</programlisting>
<para>
-Write this recipe as "publish.aap" and execute it with <userinput>aap -f
-publish.aap</userinput>. There is no need to specify the target to be built, since the
-last line specifies that the default target "all" depends on "publish" and the
-"publish" target publishes all files with a <literal>publish</literal> attribute.
-</para>
-
-<para>
-In the first line the <computeroutput>:include</computeroutput> command is used to include
-the recipe "main.aap".
-This works like the contents of "main.aap" was present in place of the
-<computeroutput>:include</computeroutput> command.
-The "main.aap" recipe defines <literal>Source</literal> and <literal>Header</literal>.
-Including this avoids having to list the source files again.
+Now you can use <userinput>aap publish</userinput>
+to upload your source files as well.
</para>