Projects Basics

Projects are the mechanism the development environment uses toorganize your source code.  At a minimum you will have one project. You mayhave as many as you desire. It all depends on how you want to organize and partitionyour source code. Projects are a collection of source files, resource files, objectcode and other projects. Each item in a project is called a module.You explicitly add modules to your project before you use the modules. Once a moduleis added to a project the environment then tracks the usage of the module. It willdetect if the file has been altered in some way by programs external to the environment.It does this to ensure that the project options and settings for each module typeare correctly adhered to.

Getting started

1. Create one or more projects. How you organize your code is entirely up to you.
2. Setup the directory search options.
3. Add your source modules to the project.
4. You are now ready to build your application(s).

Source file scanning

The environment scans your source files for imports of othersource files. It then makes sure that modules are added to the project for theseimports. It makes sense to do this because if you add a module to a project and itdepends on others, then the others should be in the project as well, and why shouldn'tthe environment save you from this tedious busy work. Given this, when you add amain program module to a project all of the modules necessary to link an executablefile for the program will automatically be added to the project for you. You arenow ready to link, run or debug your program.

Finding files

A project has various search path options that it uses to findfiles on disk when you add a module to a project. These path lists are searched fromleft to right to find the source file for a module which has been added to a project.Relative directory paths are relative to the project file. Generally it isbest to always use relative directory paths.

You may use environment variables in the search paths. Simplysurround the environment variable name with {}. For example, to use the HOME environmentvariable, use {HOME}. Environment variable names are treated case sensitively.

A module can be in a project and not have any source file found.Such modules are displayed with a flag. This usually happenswhen one module imports another module and the source file for the second modulecould not be found. Remember that the environment automatically adds modules to aproject when scanning source files. It is not possible to add a module manuallywhose source file does not exist.

If the source file for a module could not be found then the environmentstarts searching imported projects for the module. The projects are searched in thereverse order in which they were added to the project. Given this order of searching,you can create projects that override, or replace, one or more modules from anotherimported project. This operation is completely transparent to the application codeusing the modules.

You can tell the environment you want imported projects searchedfirst, and then search for actual source files in the source paths. This option isset in the Project Options dialog. The reason for doing this would be if all of yoursource files were in a single directory and you have multiple projects, of whichsome may be DLLs, and you want certain modules to be imported from certain projects.Without this option all projects would be sharing the same source directories andtherefore all projects would find the source files and therefore each project willwant to compile the file(s) themselves.

Not all module types use this directorysearch process. Only code source files, Windows resource files, external object libraryand shared object files use the search process. Other module types use are addedspecifically with appropriate path information.

See the Linking your programs topicfor information regarding resource files, object library and shared objects.

Naming of modules and files

Module names may be up to sixty-four characters in length. Actuallythe name may be longer but only the first sixty-four are considered, and the restare ignored. Module names in the environment are not case sensitive. The Module nameis the same as the source file name. This implies that all Modula-2 modules and allAda95 packages, and procedure modules, must have the symbol name the same as thefile name.

The development system does support a mode where a module/packagename is longer than eight characters but the filename is only eight characters long.This is to allow compatibility with DOS, tools, utilities and network file systemsthat do not support long file names. When a module/package name is longer than eightcharacters and the file name is exactly eight characters and they are the same firsteight characters of the module name, the environment will accept the file as thesource file for the module. This implies that cannot have two modules names are thesame in the first eight characters and use truncated file names for the sourcefiles.

If the source file uses a truncated filename, then the compileroutput files, '.sym', '.obj' and '.lib', will have a truncated filename.

If you are using the truncated file name support of the environment,you always add modules to the project using the full name of the module and let theenvironment file scanner determine if a module is using a truncated file name. Otherwise,the environment may become confused and you might end up with two copies of the samemodule in a project.

Modula-2 symbol names are case sensitive, however many file systemsare not case sensitive when matching file names, although they may store file namescase sensitive. This does require a restriction that module names cannot differ onlyin case when the file system does not support case sensitive file names. No attemptis made by the compiler or environment to enforce this restriction on files systemswith case insensitive file names.

If you are developing for DOS or DOS extended you will need tohave file names that conform to the 8.3 convention if you want to view the sourcefiles in the debugger. This is because the debugger itself is a DOS extended programand cannot access long file names. When creating new modules you should make sureyou use truncated file names, which is environment default for these applicationtargets. You create the module with its full length name and the environment willautomatically create filenames that are truncated.

The development system assumes certain file extensions for thevarious module types.

For Ada95. Since Ada95 does not have a concept of a program,only that of compilation units, we have created a convention that when followed designatesa file as a main program entry point. Ada95 program entry points are Ada proceduremodules with an '.ada' file extension, where a normal Ada95 procedure module hasan '.adp' file extension. The development system recognizes this and automaticallygenerates program entry and startup information for you. The procedure in the '.ada'source file will be called as the entry point into your program. Main program modulesare identified with the PGM module type in the project window.

Importing projects

We are all familiar with code libraries which contain code thatwe use but do not edit or compile. They only need to be linked into our application.With the development environment this is done by placing these modules into a projectand building the project. Anyone wanting to use this code would import the projectfile and not refer to source files directly (more on this later). The project filecontains all the information about all of the modules in a project and any projectimporting another project can find what it needs by referring to this informationwhen attempting to find a module.

A module can only be compiled within its native project. Modulesfrom imported projects must already be compiled to be able to use them. The environmentwill inform you when you attempt to use a module from another project that has notbeen compiled, or if the compiler options have changed since the file was last compiled.

Classes of projects

While there is no official classification of project types, otherthan a DLL project, projects fall into three categories. These categories are derivedfrom the intended use of the project.

• Application project. This project contains one or more application programs. An application project will likely import from one or more of the following project types. For example, the Runtime Library project is always imported into all projects.
• Code Library project. This project contains modules that are probably shared among multiple other projects. This is pre-compiled code that is linked into every application that refers to the code in this project. Source code for the modules in this project is not necessary for other developers to use the modules from this project. Code library projects can contain programs, it is just that programs are never exported from a project. These programs could be test programs for the utility modules contained in the project.
• DLL (dynamic linked library) project. In the Unix world these are called shared objects. This is a Code Library project with different clothes. Application projects that refer to this project do not link the code from this project into themselves, they merely refer to the DLL generated by this project. The applications will not run unless the DLL is properly installed with the application.

Compiler object files

When our compiler compiles a file it generates an output file.The type of output file depends on the input file.

Modula-2 DEFINITION modules and Ada95 Package specification filesgenerate a '.sym', or Symbol, file. These files are output into the SYM directoryoption. It is this file that is read when one module imports another.

All other Modula-2 and Ada95 module types generate an '.obj'or '.lib' file. These files are output into the OBJ directory. This directory isset with the project Directories Options.

These directory options must be relative directory paths to theproject file. This restriction is so that a project can be copied to some other systemand used. The object files can always be found because they are relative to the projectfile. Generally a directory one level deeper than the project file is used for theSYM and OBJ directory option. The default directory options use this type of relativedirectory path.

Building code library projects

The environment is very intelligent and flexible when creatingcode library projects. Normally when creating a code library project you combineall modules in the project into a single combined object library. This is done usingthe Build Menu Make object library command. Using a combined library speeds up linkingand makes copying a project to other directories much easier. The single combinedlibrary file contains all of the object files of the modules in the project. Programmodules are not added to the combined library file since you cannot import symbolsfrom program modules. This means you can leave any test programs for the librarymodules in the project. The environment keeps track of where each modules objectfile is to be found. It is either in a combined object library or it is a stand alonefile.

For example, if you created a combined object library for a projectand then later compile a single module, the environment will know that the moduleshould be linked directly and not from the combined library. All other modules willbe linked from the combined library. The module compiled after the combined librarywas built still exists in the library file. However, given the rules of linking,the code in the combined library will never be used since the stand alone file islinked before the combined library. If you then rebuild the combined library, themodule will then be linked via the combined library file.

Additionally the environment allows you to allow/disallow a modulefrom being exported from the project. By default all modules are exported. Use theModule Menu to change the export option of a module.