ALFS DTD

To ensure that all readers of the ALFS DTD Book get as much as possible from its contents, it is necessary to provide a quick introduction to the concepts of XML and DTD syntax.

To begin, here are some basic rules of XML :

As mentioned in the last section, the ampersand symbol cannot be used by itself. There are a set of standard entity references that every DTD file should contain. There are mostly symbols that you would want to place inside the XML file. You define them by using thier decimal value on the ASCII chart. Here is a good list :

Generally, you can assume that amp, lt, gt, and apos are predefined, but you can always make sure by using the numeric references above. Also, if you ever need to create your own, you know how to do it now.

XML is designed to hold any kind of information. This information is stored in Elements. Elements are the basic building blocks of XML and are represented in a XML document as tag pairs. Attributes provide a mechanism to further define or classify an element. Elements have relationships with other elements in a document. Some are parents and some are children. Using this semantic description, one can see that children elements need parent elements defined and used first. As mentioned in the last section, an XML document must have a root element. Think of this as the ultimate parent element. The root element must be defined and used before all other elements and all sub-elements (children). All elements and sub-elements will reside inside of the root element. An element can have parsed content, mixed content, simple content, empty content or attributes in their definition.

XML elements must follow these naming rules :

Once an XML document is written, it is generally a good idea to validate the elements used in the document against a known DTD. The Document Type Definition is the mechanism with which one validates the content of a well-formed XML document.

XML DTD files contain :

Elements are declared in the DTD file using a simple, but strict syntax. There are four ways to define an element :

When an element is declared with children, it will also define how the children can be used inside an XML document and also in the order that they are allowed to appear in an XML document. There are four ways that children elements can be defined in a DTD file :

As mentioned above, attributes can help to define "classes" of Elements. Attributes are defined with types and values. There are 11 types :

There are four value options :

The DOCTYPE declaration is used in an XML document to define to the XML parser what DTD should be referenced. This declaration is helpful when you have a seperate DTD file outside of the XML document. See Element : <alfs> for an example.

The SYSTEM declaration is used in an XML document to give provide a way to split up a file into smaller chunks. Many XML files can be quite large and having all the information inside one file can be unwieldy. The SYSTEM declaration works just like any ENTITY declaration. See Element : <alfs> for an example.

<!ELEMENT alfs           ((configure | copy | download | execute | link | 
                           make | mkdir | move | ownership | package | 
                           patch | permissions | remove | search_replace | 
                           stage | textdump | unpack | include)+)>
<!ATTLIST alfs
          base           CDATA #IMPLIED
          version        CDATA #FIXED "3.1"
          xml:base       CDATA #IMPLIED
          xmlns:xi       CDATA #IMPLIED>

See also : Element : <configure> | Element : <copy> | Element: <download> | Element: <execute> | Element: <link> | Element: <make> | Element: <mkdir> | Element: <move> | Element: <ownership> | Element: <package> | Element: <patch> | Element: <permissions> | Element: <remove> | Element: <search_replace> | Element: <stage> | Element: <textdump> | Element: <unpack> | Element: <include>

The alfs element is the root element of an ALFS profile document. This means that an ALFS profile should contain one and only one alfs element with all the other elements being embedded (used) within this element.

When processing an alfs element, you processes all its embedded children in their order of occurrence.

The base attribute allows you to specify the directory in which the operation will be performed. For a better description, see Element : <base>.

The version attribute identifies the version of the ALFS profile syntax used; it should be "3.1".

The include element and the xml:base and xmlns:xi attributes allow you to use xi:include directives in your profile(s).

<!DOCTYPE alfs SYSTEM "alfs-3.1.dtd" [

        <!ENTITY % general_entities SYSTEM "entities/general">

        %general_entities;

]>

<alfs version="3.1">

 .....

</alfs>

There is no equivalent Bash script example for this element.

<!ELEMENT archive        (#PCDATA)>

This element occurs in : Element: <unpack>.

The archive element is used to specify the archive file in an unpack operation.

Refer to Element: <unpack> for an example.

<!ELEMENT base           (#PCDATA)>

This element occurs in : Element: <stageinfo>

This element occurs as an attribute in the elements : Element : <alfs> | Element : <configure> | Element : <copy> | Element: <execute> | Element: <link> | Element: <make> | Element: <mkdir> | Element: <move> | Element: <ownership> | Element: <patch> | Element: <permissions> | Element: <search_replace> | Element: <textdump>

The base element when used as an element specifies the base directory which will be used by all the commands in the stage (inherited), unless another base is specified at the level of the command as an attribute.

The base element when used as an attribute specifies the base directory which will be used by any parent element it was called from.

<stage name="Install gzip">

        <stageinfo>

                <root>/mnt/lfs</root>
                <user>lfs</user>
                <environment>
                        <variable name="PATH">/bin:/sbin</variable>
                </environment>
                <base>/usr/src/gzip.1.2.4a</base>

        </stageinfo>

        <configure>
        </configure>

        <make>
        </make>

        <make>
                <param>install</param>
        </make>

</stage>

The equivalent bash script is :

echo Executing configure
su - lfs
export PATH=/bin:/sbin
cd /usr/src/gzip.1.2.4a
./configure

echo Executing make
su - lfs
export PATH=/bin:/sbin
cd /usr/src/gzip.1.2.4a
make

echo Executing make
su - lfs
export PATH=/bin:/sbin
cd /usr/src/gzip.1.2.4a
make install

echo Exiting stage

<!ELEMENT configure      ((param | prefix)*)>
<!ATTLIST configure
          base           CDATA #IMPLIED
          command        CDATA #IMPLIED>

This element occurs in : Element : <alfs> | Element: <stage>

See also : Element: <param> | Element: <prefix>

The configure element is one of the top-level operation elements. The configure element is used to describe the configure command.

When processing the element, you execute the command ./configure with the parameter(s) and prefix(es) specified.

The base attribute allows you to specify the directory in which the operation will be performed. For a better description, see Element : <base>.

The command attribute allows you to specify a custom command if you don't want to use the default ./configure. This is extremely useful when running ./configure in a build directory outside the main source directory. The packages gcc and glibc often require this.

This first example calls configure without any parameters :

<configure base="/usr/src/mypackage/">
</configure>

The equivalent bash script is :

echo Executing configure
cd /usr/src/mypackage/
./configure

This second example calls configure with some prefixes and a parameter :

<configure base="/usr/src/mypackage/">
        <prefix>CFLAGS="..."<prefix>
        <prefix>CXXFLAGS="..."<prefix>
        <param>--prefix=/opt/mypackage</param>
</configure>

The equivalent bash script is :

echo Executing configure
cd /usr/src/mypackage/
CFLAGS="..." CXXFLAGS="..." ./configure --prefix=/opt/mypackage

This third example calls configure with a parameter and uses prefix :

<configure base="/usr/src/mypackage/">
        <prefix>PATH=/usr/local/bin</prefix>
        <param>--prefix=/opt/mypackage</param>
</configure>

The equivalent bash script is :

echo Executing configure
cd /usr/src/mypackage/
PATH=/usr/local/bin ./configure --prefix=/opt/mypackage

<!ELEMENT content        (#PCDATA)>

This element occurs in : Element: <textdump>.

The content element is used to specify the content of the file being created when processing a textdump operation.

<textdump base="/etc">

        <file>group</file>

        <content>
                =root:x:0:
                =bin:x:1:
                =sys:x:2:
                =kmem:x:3:
                =tty:x:4:
                =tape:x:5:
                =daemon:x:6:
                =floppy:x:7:
                =disk:x:8:
                =lp:x:9:
                =dialout:x:10:
                =audio:x:11:
        </content>

</textdump>

The equivalent bash script is :

echo Generating file group
cd /etc
cat > group << 'EOF'
root:x:0:
bin:x:1:
sys:x:2:
kmem:x:3:
tty:x:4:
tape:x:5:
daemon:x:6:
floppy:x:7:
disk:x:8:
lp:x:9:
dialout:x:10:
audio:x:11:
EOF

<!ELEMENT copy           (option*, source+, destination)>
<!ATTLIST copy
          base           CDATA #IMPLIED>

This element occurs in : Element : <alfs> | Element: <stage>

See also : Element: <option> | Element: <source> | Element: <destination>

The copy element is one of the top-level operation elements and is used to copy one or more files and/or directories to a specified destination.

The option child-element provides a means to pass an option to the cp command.

The source child-element is required and can be used multiple times to provide multiple source files and/or directories.

The destination child-element is required and can only be used once. A copy can only have one destination.

The base attribute allows you to specify the directory in which the operation will be performed. For a better description, see Element : <base>.

<copy base="/usr/src/mypackage">
        <option>force</option>
        <source>config.txt</source>
        <destination>/opt/mypackage/config.txt</destination>
</copy>

The equivalent bash script is :

echo Copying 'config.txt into /opt/mypackage/config.txt'
cd /usr/src/mypackage
cp -f config.txt /opt/mypackage/config.txt

<!ELEMENT description    (para | list)*>

This element occurs in : Element: <packageinfo>

See also : Element: <para> | Element: <list>

The description element contains the description of a package. Its use is for documentation only.

Refer to Element: <packageinfo> for an example.

There is no equivalent Bash script example for this element.

<!ELEMENT destination    (#PCDATA)>

This element occurs in : Element : <copy> | Element: <download> | Element: <move> | Element: <unpack> |

The destination element is used to specify the name of the destination file or directory when processing an element in which it occurs.

The first example is an unpack command.

<unpack>
        <archive>/usr/src/lfs-packages/gzip.1.2.4a.tar.gz</archive>
        <destination>/usr/src</destination>
</unpack>

The equivalent bash script is :

echo Unpacking /usr/src/lfs-packages/gzip.1.2.4a.tar.gz into /usr/src
cd /usr/src
tar -xzvf /usr/src/lfs-packages/gzip.1.2.4a.tar.gz

The second example is a copy command.

<copy base="/usr/src/mypackage">
        <option>force</option>
        <source>config.txt</source>
        <destination>/opt/mypackage/config.txt</destination>
</copy>

The equivalent bash script is :

echo Copying 'config.txt into /opt/mypackage/config.txt'
cd /usr/src/mypackage
cp -f  config.txt /opt/mypackage/config.txt

<!ELEMENT digest         (#PCDATA)>
<!ATTLIST digest
          type           CDATA "md5">

This element occurs in ; Element: <download> | Element: <unpack>

The digest element is used to specify a unique digest of the file to be operated on by the parent element. Typically these digests are MD5 sums, but an ALFS implementation can support alternative digests as well, including SHA-1.

The type attribute specifies the algorithm used to create the specified digest value, and defaults to MD5 if not specified.

Refer to Element: <reference> for an example.

There is no equivalent Bash script example for this element.

<!ELEMENT download       (file, url*, destination, digest?)>

This element occurs in : Element : <alfs> | Element: <stage>

See also : Element: <file> | Element: <url> | Element: <destination> | Element: <digest>

The download element is one of the top-level operation elements. It is used to specify one or several URLs from which a file can be downloaded; optionally a digest to check that the file being downloaded is the right one and was downloaded correctly (not corrupted or truncated).

The file child-element contains the name of the file to be downloaded.

The url child-element contains the url of the directory from which the download is performed. It should be terminated by a slash [ / ]. More precisely, the actual URL used for the download is the catenation of the content of the url element with the content of the file element.

The destination child-element contains the path of the directory into which the download should be performed.

The digest child-element contains the value to which the digest computed from the dowloaded file will be compared. See Element: <digest>.

If the file is already present in the destination directory, no download is performed but the digest is checked if specified.

<download>
        <file>gzip-1.2.4a.tar.gz</file>
        <url>ftp://gnu.org/</url>
        <destination>/tmp/</destination>
</download>

The equivalent bash script is :

echo Executing 'download'
wget -nc -O /tmp/gzip-1.2.4a.tar.gz ftp://gnu.org/gzip-1.2.4a.tar.gz

<!ELEMENT environment    (variable+)>
<!ATTLIST environment
          mode           (append | prepend) #IMPLIED>

This element occurs in : Element: <stageinfo>

See also : Element: <variable>

The environment element allows you to define one or more environment variables to be added to the system environment used when calling the commands of the stage to which it applies.

By default, the supplied value replaces any existing value for the specified variable. The mode attribute allows you to specify whether the supplied value should be prepended or appended to the existing value.

<stage>
        <stageinfo>

                <base>/usr/src/gzip.1.2.4a</base>

                <environment>
                        <variable name="GCCFLAGS">-O2</variable>
                        <variable name="PATH" mode="prepend">/usr/src/gzip.1.2.4a:</variable>
                        <variable name="LDFLAGS" mode="append"> -s</variable>
                </environment>

        </stageinfo>

</stage>

The equivalent bash script is :

echo Stage

export GCCFLAGS=-O2
export PATH=/usr/src/gzip.1.2.4a:$PATH
export LDFLAGS="$LDFLAGS -s"

echo Exiting stage

<!ELEMENT execute        ((param | prefix)*)>
<!ATTLIST execute
          base           CDATA #IMPLIED
          command        CDATA #REQUIRED>

This element occurs in : Element : <alfs> | Element: <stage>

See also : Element: <param> | Element: <prefix>

The execute element is one of the top-level operation elements. It is used to execute any arbitrary system command.

The param child-element contains parameters for the command.

The prefix child-element contains any prefix data for the command to execute.

The base attribute allows you to specify the directory in which the operation will be performed. For a better description, see Element : <base>.

The command attribute contains the text of the command itself.

The first example is an execute command without a parameter.

<execute command="umount">

The equivalent bash script is :

echo Executing 'umount'
umount

The second example is an execute command with one parameter.

<execute command="mount">
        <param>/mount/lfs</param>
</execute>

The equivalent bash script is :

echo Executing 'mount'
mount /mount/lfs

<!ELEMENT file           (#PCDATA)>

This element occurs in : Element: <download> | Element: <search_replace> | Element: <textdump>.

The file element is used to specify the filename for a download, search_replace or textdump operation.

See any one of the parent elements for an example.

<!ELEMENT find           (#PCDATA)>

This element occurs in : Element: <search_replace>