6 How to Start a New Project with ALLPROSE

1. Get ALLPROSE. Unpacking it via

   gunzip -c allprose-x.y.z.tar.gz | tar xvf -

   creates a directory allprose-x.y.z. It is suggested to rename allprose-x.y.z to reflect the name of your project. In the following it is assumed that the name of the new project is MyProject and that it resides in the directory ˜/myprojectdir, i. e., you renamed the directory allprose-x.y.z into myprojectdir.

2. Make sure by consulting Section 9 that you have all necessary software installed.
3. Test whether the current pure ALLPROSE distribution compiles on your machine.
   1. The command

      make dvi

      compiles the text you are currently reading into a .dvi format.

   2. Calling

      make rm-local.sty colored dvi

      makes it more colorful.

   3. By calling

      make check

      it should be possible to compile the libraries and run the (debug variant) of the testsuite.

If you encounter any problems with the steps above, try to ask for help at ralf@hemmecke.de.

Now you have ALLPROSE working. Building your own library is basically a matter of telling ALLPROSE the name of you project and writing appropriate .as.nw files.

It is, in fact, a little more work. So let us go through the steps.

1. After calling make dvi, you should have a file Makefile.def.nw (which is a copy of Makefile.def.allprose.nw) in the ALLPROSE root directory (which is actually now your PROJECTROOT directory³ ).
2. Go to the place in Makefile.def.nw where PROJECTNAME is defined and replace $(ALLPROSELIBPROJECTNAME) by MyProject. Set the other values in that code chunk of Makefile.def.nw as described in the accompanying text, in particular, set the variables projectname to myproject and LIBPREFIX to mp. Additionally, you might want to change the CREDITS variable.

   Changing the project name in the copyright notice from

   --- ALLPROSE

   to

   --- MyProject

   is important for an upgrade of ALLPROSE, see Sections 10 and 28.12.

   For the moment, the rest of Makefile.def.nw can be left unmodified.

3. Copy myalps.tex.nw⁴ to myproject.tex.nw and modify the copyright notice of the new file in order to reflect that this file now belongs to you. Modify the author(s) and change the title and author in the code chunk of myproject.tex.nw.⁵
4. Copy also myalps.bib.nw and myalps.sty.nw to myproject.bib.nw and myproject.sty.nw, respectively. Modify the copyright notice of myproject.sty.nw and change the definition appearing in Section 14.1 accordingly.
5. Copy include/myalps.as.nw to include/myproject.as.nw and change the copyright notice in the new file. Additionally, replace all appearances of MyAlps and myalps by MyProject and myproject, respectively. At least you should change MacrosMyAlps, DontNeedLibraryMyAlps, "myalps", and "myalpsd".

The file myproject.tex is the main entry point of the documentation of your project. It will be generated from the code chunk in myproject.tex.nw.

Check whether everything works as expected by typing the following.

Be warned that we describe here only the first steps to start a project.⁶ Of course, the result is not as described below, after you have modified the file myproject.tex.nw.

After executing the commands above you should type

and note that by some magic the projectname MyAlps has been replaced by MyProject. By design, the file allprose.tex.nw has been written in such a way that it may or may not be included into a project, different from MyAlps. See Section 24.1 for more details. If you are familiar with ALLPROSE you certainly do not need to include that file anymore.⁷ In fact, you should just document your own project and thus distribute the things that are important for you. You have, however, the option of including the documentation of the ALLPROSE framework. The references to the project name MyAlps in the ALLPROSE documentation would then be automatically replaced by the name of your project. The documentation of the ALLPROSE framework would thus seamlessly integrate into the whole documentation.

The next steps demonstrate how you have to modify myproject.tex.nw in order to remove the reference to the directories src/myalps and test/myalps and how you add your first Aldor files.

1. Make a new directory src/basic.⁸
2. As a sample file copy src/myalps/binpow.as.nw to src/basic/binpow.as.nw. Modify the copyright notice of that file and change the lines

   #assert DontNeedLibraryMyAlps   #include "myalps"

   to

   #assert DontNeedLibraryMyProject   #include "myproject"

   and leave the rest of the file as it is. That file is just used for demonstrating how your Aldor files should look like and what you have to modify in order to make them known to the ALLPROSE framework.

3. Make a new directory test/basic.⁹
4. As a sample file copy test/myalps/binpow.as.nw to test/basic/binpow.as.nw. Just modify the copyright notice of that file.
5. In Section 4 is a list of all Aldor source files¹⁰ of the project together with a short (informal) description of what the files contain and (maybe) their relations to each other. In fact, any information that is useful for other people to get a rough overview of the library should be written in this section.

   The file myproject.tex.nw is the only place where the Aldor source files that form the project MyProject are made known to ALLPROSE. There is no need to edit any Makefile in ALLPROSE. It is also (usually) unnecessary to state the dependencies among the source files, because ALLPROSE takes care of dependencies. The source files should simply appear inside a ∖sourcefile command.

   Edit Section 4 in the file myproject.tex.nw (and not in myalps.tex.nw). Replace

   \sourcefile{src/myalps/binpow.as}

   by

   \sourcefile{src/basic/binpow.as}

   and remove the lines corresponding to the description of the other files in the directory src/myalps.¹¹

6. In Section 4 is a also list of all Aldor source files that form the testsuite of the project.

   As with the source files that form the library, the testsuite files must be listed in myproject.tex.nw via the ∖sourcefile command.

   Edit Section 4 in the file myproject.tex.nw (and not in myalps.tex.nw). Replacing

   \sourcefile{test/myalps/binpow.as}

   by

   \sourcefile{test/basic/binpow.as}

   is all in order to get a sample testsuite.

Now you have your own little project MyProject. You should test whether everything works fine. Typing

first removes all generated files and then produces the documentation (without any reference to the files under the directories src/myalps and test/myalps), compiles the library and compiles and runs the testsuite.

Whenever you add a new Aldor source file to the library or to the testsuite, you have to make it known to ALLPROSE by following the steps above. Note that you should write the Aldor source files without any prefix as, for example, is done by using the prefixes sal_ and ald_ in the sources of the library Aldor and the prefixes sit_, sm_, and alg_ in the library Algebra. ALLPROSE lets you specify a global prefix (which was mp in the demonstration above). The files in the project library will all carry this prefix. It is, therefore, easy to avoid name conflicts of the files in different libraries. It is just a matter of redefining LIBPREFIX and recompiling the library. The prefix tc is reserved for the testcases library.

ALLPROSE automatically generates a file src/mymyalpsversion.as with a package that contains information about the version of your library, see also the generated file src/mpmyprojectversion.as and Section 33.3 for the code that does the generation.