2.2.2. Projects and sub-projects

An APM project is a description of how you build something, such as an image or object library, and a list of the files you need, such as source files, include files, and any sub-projects.

APM describes what you are building and how you build it by means of a project template. A template consists of a series of build step patterns that define the build steps used to construct the output of your project.

A sub-project is simply an APM project that has been added to another project. For example if you have a project that builds a library, it could become a sub-project of another project that makes an image using routines from that library.

Project files

A project manages source files, and derived files created from source files by the build tools.

Source files form the basis of a project. Symbols in the Project window indicate various types of source file, as shown in the following list. The source file types recognized by the standard templates are:

C or C++ source file

ARM assembly language file

include file

sub-project (this is also a type of source file, contributing its own project output to the current project)

file of a type unknown to APM.

When you add a source file to a project, it is not copied or moved from its original location in the file system. Its location is referenced from the project file. Whenever possible APM refers to files relative to the project directory structure rather than absolutely. You can set the variable $$DepthOfDotAPJBelowProjectRoot to increase the scope of the directories that are considered a part of the project. Refer to Variables for more information.


If you move a project, you must keep the directory structure containing its files the same. If you change the directory structure, the files required to build the project will not be found.

Derived files are created as the result of a build step, such as a compile or a link.

An object file

A library

An ARM executable image.

Creating a new project

Follow these steps to create a new project:

  1. Select New from the File menu or click the

    New button. The New dialog is displayed (Figure 2.1).

    Figure 2.1. New dialog

    New dialog
  2. Select Project from the scroll box.

  3. Click OK. The New Project dialog is displayed (Figure 2.2).

    Figure 2.2. New Project dialog

    New Project dialog
  4. Select the template Type that you want to use for the project. The template description is displayed. For this example select ARM Executable Image.

  5. Enter a Project name, such as hello. This is used for the project file and the project output.

  6. Modify the Project Directory to c:ARM250\Examples\hello. When you build the project, the directories containing derived files (variant directories) are created within this directory.

  7. Click OK.

    If you have specified a directory that does not currently exist, you are prompted to confirm that you want a new project directory created. The new project file is created in the project directory and the Project window is displayed.

Creating a new source file

For the hello project you created in the previous section, follow these steps to create a new source file from within APM:

  1. Click the New button or select New from the File menu. The New dialog appears.

  2. Select C/C++ source from the scroll box.

  3. Click OK. An Edit window is displayed.

  4. Enter the following code, deliberately omitting the semicolon at the end of the printf() function call:

    #include <stdio.h>
    int main(void)
    	printf("Hello World\n") 
    	return 0;
  5. Save the code in a source file by selecting Save or Save As... from the File menu or by clicking the

    Save button. Enter hello.c when you are prompted for a filename.

  6. Close the Edit window by selecting Close from the File menu. You are now returned to the Project window with the hello project loaded.

The source files and files inferred by the build steps are organized in a project using partitions (as described under Partitions). APM uses variants to create different versions of your project output. By default the following variants are defined:


This variant is designed for projects where you intend to release the same code that you are debugging. It provides an adequate debug view, together with good optimization. This variant sets the debug and optimization command-line options to -g+ -O1.


This variant is designed for projects where you intend to have separate debug and release builds of your code. It contains the debug version of your project and provides maximum debug information at the expense of optimization. This variant sets the debug and optimization command-line options to -g+ -O0.


This variant is designed for projects where you intend to have separate debug and release builds of your code. It contains the release version of your project. It provides maximum optimization at the expense of debug information. This variant turns off debug table generation and sets the optimization command-line option to -O2.

Adding files to a project

Follow these steps to add the newly created file to your project:

  1. Select the hello project as the current project.

  2. Select Add Files to Project from the Project menu. The Open File dialog box is displayed.

  3. Move to the correct directory, if necessary, and select hello.c.

  4. Click Open. The file is added to the project.


If the project directory is still your current directory, that is where the source file is stored by default. You can, however, store source files in any accessible directory, and add source files from any directory to a project.

Viewing the project

When you have added files to your project, you may want to view the project in more detail. To expand a level of the project hierarchy, click on the plus (+) symbol next to that level. Figure 2.3 shows how the Project View looks if you expand the first three levels of hello.apj.

Figure 2.3. Expanded view

Expanded view

You can see that hello.c, the file you added to the project, is now in the Sources partition. The files hello.o and hello.axf have been added to the Objects and Image partitions. These are the derived files that are the anticipated

output of the project build steps. The work in progress symbol indicates that they have not yet been built.

Other options for viewing a project are discussed in Changing the way a project is displayed.


APM displays nested source dependencies only if the compiler and assembler are invoked with the -MD- command-line option. This option instructs the assembler and compiler to output source dependencies to the Project Manager. The project templates shipped with APM specify this option in the build step pattern.

Copyright © 1997, 1998 ARM Limited. All rights reserved.ARM DUI 0040D