The ALLPROSE source files consist mainly of the Makefiles and scripts in any directory together with the documentation file allprose.tex.nw which you are currently reading.
There are also some Aldor files provided by ALLPROSE that can serve as templates for new projects. They reside under the subdirectory myalps of the directories src and test. The general include files are in directory include. Tools that support the building process can be found in directory tools.
This section is intended to describe all files that belong to the ALLPROSE framework. These files are used for building the library together with its documentation.
Files that are not mentioned in this section and not tagged via the LATEX command ∖sourcefile will not appear in the documentation. The library files are described in myalps.tex.nw. For each file a short summary should be given
It loads Makefile.def.nw and Makefile.inc.nw.
This script extracts the addescription environment from the +++ description if the corresponding Aldor code chunk contains a function or constant declaration. It writes out the (embellished) function declaration together with an adshortdescription environment.
During the compilation of the documentation starting with myalps.tex, a file myalps.lsf will be generated in which every call to ∖sourcefile in the whole documentation is listed. We want the files described in the whole documentation (actually only myalps.tex.nw and allprose.tex.nw should count) to match the files listed in the Makefiles.
For the generation of the whole documentation we use allprose.sty.nw and myalps.sty.nw, together with several other packages as defined in allprose.sty.nw.
Among those packages is aldordoc.sty.nw. It contains a number of LATEX commands for the structured documentation of Aldor +++ descriptions. Since not all commands described in the interface of aldordoc.sty.nw come with an actual LATEX implementation in aldordoc.sty.nw, there is a script tools/aldordoc2tex.pl.nw that translates the aldordoc interface to an actual aldordoc implementation. Currently, aldordoc (i. e., aldordoc.sty.nw and tools/aldordoc2tex.pl.nw) is part of ALLPROSE, but in the future it might be distributed separately.
A number of LATEX commands from allprose.sty.nw generate and include the files mentioned in this file (allprose.tex.nw). Local customization is possible through the file local.sty.
In order to produce an .html form of the documentation, we employ TEX4ht. There is some adjustment necessary which we have put into the allprose.4ht.nw. That file is only necessary for TEX4ht.
The top-level Makefile.nw contains all necessary targets to build the complete project.
Via the file Makefile.def.nw the name of the project and its version should be set. The file Makefile.def.allprose.nw only serves as a template for Makefile.def.nw and is not used if Makefile.def.nw is present. In fact Makefile.def.nw is the only file of ALLPROSE that should and must be changed by a library writer. It is not distributed with ALLPROSE, but will be generated (as a copy of Makefile.def.allprose.nw) the first time that make is called.
The top-level Makefile.nw includes the files Makefile.def.nw and Makefile.inc.nw for targets that are common for the subdirectories.
In fact, Makefile.def.nw and Makefile.inc.nw are included into every Makefile in any subdirectory of the project.
Due to a bug in Noweb we need the script tools/nwescape.pl.nw in order to escape unpaired << and >> occurrences.
It is important that the scripts in the directory tools are available. That is why first the contents of this directory is built via tools/Makefile.nw.
ALLPROSE builds two sets of libraries, one for the project and the other one that collects the testcases of the project. In fact, ALLPROSE builds src/libmyalps.al and test/libtestcases.al and all their variants (see Section 15.2).
The directory include is used for the Aldor source files that are included into other Aldor source files. Basically, the file include/Makefile.nw simply builds the files include/myalps.as.nw and include/testcases.as. The latter is generated by the script tools/generateTestCases.pl.nw mainly in order to get the line
#include "projectname"
|
correct, where projectname is replaced by the true name of the project (here myalps).
The file include/myalps.as.nw is the main include file that should be included in each .as file that uses the MyAlps library. We also build the library incrementally so that even the MyAlps library source files can include include/myalps.as.nw. It is possible not to load the MyAlps library although include/myalps.as.nw is included.
Similarly, include/testcases.as is included into each testcase file. It is possible not to load the testcases library.
The Aldor source files reside under the directory src. The file src/Makefile.nw includes Makefile.inc.nw, Makefile.def.nw and src/Makefile.dep.
We support the NOWEAVE process by adding definitions of category, domain, and package constructors automatically at the end of a code chunk. This is done by filtering each .as.nw file through the script tools/addaldortypedef.pl.nw.
Furthermore, the target showexports in Makefile.nw produces via the Perl script tools/showexports2aldordoc.pl.nw exports of categories and domains in a LATEX format which will be automatically included into the documentation.
In order to determine the .as files that are about to be compiled, we parse the file myalps.tex.nw for the Perl regular expression
\\sourcefile{[^}]+\.as}
|
and generate the files src/Makefile.asfiles and test/Makefile.asfiles from the output of the script tools/asfiles.pl.nw.
In fact, ALLPROSE generates two versions of .as files from the corresponding .as.nw files.
The script tools/dependencies.pl.nw generates the files src/Makefile.dep and test/Makefile.dep.
The file src/Makefile.nw lists targets to generate the Aldor libraries from the sources. It includes the generated file src/Makefile.dep.
Since ALLPROSE is just a framework for building Aldor libraries, it does not require any specific library like, for example, the standard libraries Algebra and Aldor provided by www.aldor.org. However, for building and running the testsuite, ALLPROSE builds on Christian Aistleitner’s AldorUnit and ExtIO libraries which in turn require at least the standard library Aldor. One can specify the libraries to use via the file include/myalps.as.nw and Makefile.def.nw.
The testsuite is built by using test/Makefile.nw. The testfiles will be parsed by the script tools/generateTestSuite.pl.nw in order to generate a file test/TestSuite.as.