6.1 Makefiles and Directory Organization

The PDP++ code should be installed in `/usr/local/pdp++', or some such similar place. This path will be referred to from here on out as PDPDIR. This directory contains a set of sub-directories, like `demo' and `manual', etc. which contain different pieces of the distribution. See section 4.6 Installing the Programmers Version for instructions on how to install and compile the source distribution of the PDP++ software. In order compile your own additions to the software, you must install and compile the source code distribution!

The critical directories from a programmer's perspective are the `src', which contains the source code, `config', which contains the Makefile configuration stuff, `include' which has links to the header files, and `lib' which has links to the various libraries.

Each sub-directory within the `src' directory contains code relevant to some sub-component of the PDP++ software. These directories are as follows:

`ta_string'
The basic String class used throughout the software. It is a slightly modified version of the GNU String class that is distributed with the libg++ distribution (version 2.6.2).
`iv_misc'
Contains a number of extra pieces of code that supplement the InterViews GUI toolkit.
`ta'
Contains the TypeAccess system, which gives classes the ability to know all about themselves and other classes at run time. The use of this software is what makes the largely automatic interface used in PDP++ possible. It is described further in section 6.2 The TypeAccess System. This directory also contains a lot of basic objects, like Array (section 8.3 Arrays), List and Group (section 8.2 Groups) objects.
`css'
Contains the code for the CSS script language (see section 5 Guide to the Script Language (CSS)).
`iv_graphic'
Contains a set of objects which implement a graphical object manipulation environment that is used in the network viewer (@xref{net-view}) and the graph log (@xref{log-views-graph}).
`ta_misc'
Contains a smorgasbord of various objects that might have general applicability, and are not specifically PDP objects.
`pdp'
Where all of the specific pdp code is.
`bp'
Implements bp and rbp.
`cs'
Implements cs.
`so'
Implements so.
`bpso'
Implements the combined bp and so executable (just links the libraries).
`leabra'
Implements the leabra algorithm.

Each directory has a set of include files which can be accessed as <xxx/yyy.h>, where xxx is one of the directory names given above. In addition, each directory has its own library, which is just `libxxx.a', where xxx is the name of the directory (without any underbars). The bp, cs and so directories have a library name of libpdp_xx.a, to indicate that they are part of the pdp software.

All of the compilation results (e.g. object files) go in a subdirectory named after the CPU type being used. The user must set the CPU environmental variable appropriately, as per the definitions used in the InterViews system. The ones that everything has been tested and compiled on are listed in the installation guide (see section 4 Installation Guide), and the INSTALL file.

Other possibilities are listed in section 4.6 Installing the Programmers Version. This should be the same as when the system was first installed.

The include files and library are made in two stages. The first stage involves compiling the object files into the CPU subdirectory. Then, if everything goes ok, the library is made, which is then copied into a further subdirectory of the CPU subdirectory called `lib_include'. Also, all of the header files are compared with those already in the `lib_include' subdirectory (if any), and those ones that are different are copied over. It is these header files in `lib_include' that the `PDPDIR/include' directory makes links to, and thus these are the ones that are included by other programs. This setup allows one to test out a set of code by making an executable in a given directory and getting things working before installing the new header files and library for the rest of the system to use.

In order to add functionality to the software, one needs to create a new directory, and then include various files from the above directories, and link in their respective libraries. This directory can be located in the same master directory as the main distribution, or it can be located in your own home directory somewhere. This latter option is the preferred one.

We have developed a shell file that does all of the things necessary to create your own directory. The first step is to make a master directory off of your home directory, typically called `pdp++'.

Then, run the `PDPDIR/bin/mknewpdp' command from this new `home/pdp++' directory with an argument which is the name of the directory/executable that you want to make. This will give you step-by-step instructions. In the end, you will end up with a directory that contains some sample code in the form of a .h and .cc file with the same name as the directory.

The script will have installed a `Makefile' in your directory which is the same as the one's found in the main PDP++ directories. These makefiles are constructed by concatenating together a bunch of pieces of makefiles, some of which contain standard make actions, and others which contain specific defaults for particular machines. All of the pieces are found in the `PDPDIR/config' directory.

The makefiles named `Makefile.CPU.[CC|g++]' are the machine-specific files that you should edit to make sure they have all the right settings for your system. This should have been done already during the installation of the PDP++ source code distribution, see section 4.6 Installing the Programmers Version for details.

To these pieces is added the specific list of files that need to be made in your directory. This is specified in the `Makefile.in' file. This is the only makefile you should edit. It can be used to override any of the settings in the standard makefiles, simply by redefining definitions or actions. If you add files to your directory, follow the example for the one already in your default `Makefile.in' that was installed with the `mknewpdp' command.

Note that there are a couple of compiler-specific "extra" files in the directory. These have the name of the directory plus a `_vt.cc' or `_it.cc' suffix. The `_vt' file is for virtual table instantiation, which is controlled in cfront with the +e0/+e1 arguments. It simply includes most of the header files in the software. We have found that by compiling everything except the `_vt' file with +e0 that the executables are much smaller. This is even true in cfront versions where they had "fixed" this problem. You can try doing the other way by leaving out the +e args and not using the `_vt' file (see the definitions in `PDPDIR/config/Makefile.defs' for how to do this: change your `Makefile.CPU' file and recompile the entire distribution first..).

The `_ti.cc' is the template instantiation file needed by gnu g++ version 2.6.3 (reportedly, it won't be needed in 2.7). It contains explicit instantiations of all of the templates used in each library. For user directories, this probably isn't needed, but its there if you do declare any templates and encounter link problems with g++. Also, the `Makefile.CPU.g++' show how this file gets included in the making of a given project.

New for 2.0: All of the makefile actions, as shown below, are now available using a consistent syntax structure: all lower case, with underbars separating different words. This makes it much easier to remember what command to type. The old eclectic combinations of upper and lower case words, etc are still available if you already know them.

The commonly-used actions that are defined in the makefile are as follows:

`make bin, make opt_bin, make dbg_bin'
Makes the binary from the files in this directory. Bin makes the default form specified in the make file, while opt and dbg make optimized and debug versions, respectively.
`make re_bin, make opt_re_bin, make dbg_re_bin'
Same as above, except it first removes the executable before making. This is useful if a library has changed but no header files from that library were changed.
`make lib, make opt_lib, make dbg_lib'
Like the above, except it makes a library containing the relevant .o files.
`make new_makefile'
This makes a new version of the `Makefile' file in the current directory. This concatenates all of the different parts that together make up a single `Makefile'. However, it does not make a CPU directory, which is necessary to actually compile (see cpu_dir next).
`make cpu_dir, make local_cpu_dir'
This makes and configures a directory with the same name as the CPU environmental variable (reflecting the CPU type of the machine) suitable for compiling the object files into. If local_cpu_dir is made first, then this directory is actually a symbolic link to a directory created on a disk local to the current machine, so that compilation will be faster than if the directory where the source is located is a networked (slow) directory (i.e., NFS). The cpu_dir action copies the current `Makefile' into the directory, and configures the directory for compiling. Note that these actions remove any existing dependency information, so that a depend action should be made following either of them.
`make depend'
This automatically adds dependency information for the files in this directory onto the `CPU/Makefile' file. This allows the make command to know when to compile these files after something they depend on has been touched (edited).
`make makefiles, make make_depend, make new_make_depend'
These actions simply combine some of the above steps together into one action. makefiles does a new_makefile and then a cpu_dir, make_depend does a cpu_dir and then a depend, and new_make_depend does all three of the necessary steps: new_makefiles, cpu_dir, and depend. The only reason you should not use the latter all the time is if your make program has trouble using a new `Makefile' (i.e., as created by the make new_makefiles action) for calling the subsequent actions. In this case, you have to first do a make new_makefiles and then you can do a make make_depend.
`make force_ta'
Forces a call to the TypeAccess scanning program `maketa'.