Creating an application project

This tutorial introduces you to the IAR Embedded Workbench® integrated development environment (IDE). The tutorial demonstrates a typical development cycle and shows how you use the compiler and the linker to create a small application for your device. For instance, creating a workspace, setting up a project with C source files, and compiling and linking your application.

Using the IDE, you can design advanced project models. You create a workspace to which you add one or several projects. There are ready-made project templates for both application and library projects. Each project can contain a hierarchy of groups in which you collect your source files. For each project you can define one or several build configurations. For more details about designing project models, see the IDE Project Management and Building Guide

Because the application in this tutorial is a simple application with very few files, the tutorial does not need an advanced project model.

Before you can create your project, you must first create a workspace.

The first step is to create a new workspace for the tutorial application. When you start the IDE for the first time, there is already a ready-made workspace, which you can use for the tutorial projects. If you are using that workspace, you can ignore the first step.

Choose File>New>Workspace. Now you are ready to create a project and add it to the workspace.

You can find all the files needed for the tutorials in the cpuname\tutor directory. Make a copy of the tutor directory in your projects directory.

Note: If you copied all the files from the cpuname\tutor directory before you started with the tutorials, a project file will already be available in your projects directory. You can use that ready-made file, or create your own file.

1	To create a new project, choose Project>Create New Project. The Create New Project dialog box appears, which lets you base your new project on a project template.

3	For this tutorial, select the project template Empty project, which simply creates an empty project that uses default project settings.

4	In the standard Save As dialog box that appears, specify where you want to place your project file, that is, in your newly created projects directory. Type project1 in the File name box, and click Save to create the new project.

The project will appear in the Workspace window.

By default, two build configurations are created: Debug and Release. In this tutorial only Debug will be used. You choose the build configuration from the drop-down menu at the top of the window. The asterisk in the project name indicates that there are changes that have not been saved.

A project file—with the filename extension ewp—will be created in the projects directory, not immediately, but later on when you save the workspace. This file contains information about your project-specific settings, such as build options.

Before you add any files to your project, you should save the workspace. Choose File>Save Workspace and specify where you want to place your workspace file. In this tutorial, you should place it in your newly created projects directory. Type tutorials in the File name box, and click Save to create the new workspace.

A workspace file—with the filename extension eww—has now been created in the projects directory. This file lists all projects that you will add to the workspace. Information related to the current session, such as the placement of windows and breakpoints is located in the files created in the projects\settings directory.

This tutorial uses the source files Tutor.c and Utilities.c.

The Tutor.c application is a simple program using only standard features of the C language. It initializes an array with the ten first Fibonacci numbers and prints the result to stdout.

Creating several groups is a possibility for you to organize your source files logically according to your project needs. However, because this project only contains two files, you do not need to create a group. For more information about how to create complex project structures, see the IDE Project Management and Building Guide

2	Choose Project>Add Files to open a standard browse dialog box. Locate the files Tutor.c and Utilities.c, select them in the file selection list, and click Open to add them to the project1 project.

Now you will set the project options. For application projects, options can be set on all levels of nodes. First you will set the general options to suit the processor configuration in this tutorial. Because these options must be the same for the whole build configuration, they must be set on the project node.

1	Select the project folder icon project1 - Debug in the Workspace window and choose Project>Options. In this tutorial you should use the default settings.

3	Verify that the default settings are used. In addition to the default settings, click the List tab, and select the options Output list file and Assembler mnemonics. Click OK to set the options you have specified.

The project is now ready to be built.

You can now compile and link the application. You will also view the compiler list file and the linker map file.

Alternatively, click

the Compile button on the toolbar or choose the Compile command from the context menu that appears when you right-click on the selected file in the Workspace window.

The progress is displayed in the Build messages window.

The IDE has now created new directories in your project directory. Because you are using the build configuration Debug, a Debug directory has been created containing the subdirectories List, Obj, and Exe:

The List directory is the destination directory for the list files. The list files have the extension lst.

The Obj directory is the destination directory for the object files from the compiler and the assembler. These files have the extension rxx and are used as input to the XLINK linker. For the ILINK linker, the corresponding filename extension is o.

The Exe directory is the destination directory for the executable file. It has the extension dxx (for XLINK) and out (for ILINK), and is used as input to the IAR C-SPY® Debugger. Note that this directory is empty until you have linked the object files.

Click on the plus signs in the Workspace window to expand the view. As you can see, the IDE has also created an output folder icon in the Workspace window containing any generated output files. All included header files are displayed as well, showing the dependencies between the files.

Now examine the compiler list file and notice how it is automatically updated when you, as in this case, will investigate how different optimization levels affect the generated code size.

1	Open the list file Utilities.lst by double-clicking it in the Workspace window. Examine the list file, which contains the following information:

The header shows the product version, information about when the file was created, and the command line version of the compiler options that were used

The body of the list file shows the assembler code and binary code generated for each statement. It also shows how the variables are assigned to segments

The end of the list file shows the amount of stack, code, and data memory required, and contains information about error and warning messages that might have been generated.

Notice the amount of generated code at the end of the file and keep the file open.

2	Choose Tools>Options to open the IDE Options dialog box and click the Editor tab. Select the option Scan for changed files. This option turns on the automatic update of any file open in an editor window, such as a list file.

Click the OK button.

3	Select the file Utilities.c in the Workspace window, right-click and choose Options from the context menu to open the C/C++ Compiler options dialog box. Select the Override inherited settings option. Click the Optimizations tab and choose High level of optimization. Click OK.

Notice that the options override on the file node is indicated with a red dot in the Workspace window.

4	Compile the file Utilities.c. Now you will notice two things. First, note the automatic updating of the open list file due to the selected option Scan for changed files. Second, look at the end of the list file and notice the effect on the code size due to the increased optimization.

For this tutorial, the optimization level None should be used, so before linking the application, restore the default optimization level. Open the C/C++ Compiler options dialog box by right-clicking on the selected file in the Workspace window. Deselect the Override inherited settings option and click OK. Recompile the file Utilities.c.

Now you should set the options for the linker.

1	Select the project folder icon project1 - Debug in the Workspace window and choose Project>Options, or righ-click and choose Options from the context menu. Then select Linker in the Category list to display the linker option pages.

For this tutorial, the default factory settings are used. However, pay attention to the choice of output format (XLINK linker only) and the linker configuration file.

It is important to choose the output format that suits your purpose. You might want to load it to a debugger—which means that you need output with debug information. In this tutorial you will use the default output options suitable for C-SPY—Debug information for C-SPY, With runtime control modules, and With I/O emulation modules—which means that some low-level routines will be linked that direct stdin and stdout to the Terminal I/O window in the C-SPY Debugger. You find these options on the Output page.

Alternatively, in your real application project, you might want to load the output to a PROM programmer—in which case you need an output format without debug information, such as Intel-hex or Motorola S-records.

The linker produces an output file in the ELF format, including DWARF for debug information. If you need to have a file in the Motorola or Intel-standard formats instead, for example to load the file to a PROM memory, you must convert the file. You can use the converter provided with IAR Embedded Workbench.

In the XLINK linker configuration file (filename extension xcl), the XLINK command line options for segment control are used for placing segments. It is important to be familiar with the linker configuration file and the placement of segments.

For the ILINK linker, program code and data are placed in memory according to the configuration specified in the linker configuration file (filename extension icf). It is important to be familiar with its syntax for how sections are placed in memory.

Read more about this in the IAR C/C++ Compiler Reference Guide or in the IAR C/C++ Development Guide.

Note: In the simulator, you can use the linker configuration file templates supplied with the product as they are, but when you use them for your target system you might have to adapt them to your actual hardware memory layout. You can find supplied linker configuration files in the config directory.

In this tutorial you will use the default linker configuration file, which you can see on the Config page.

If you want to examine the linker configuration file, use a suitable text editor, such as the IAR Embedded Workbench editor, or print a copy of the file, and verify that the definitions match your requirements. Alternatively, click the Edit button to open the linker configuration file editor.

By default, no linker map file is generated. To generate a linker map file, click the List tab and for the XLINK linker, select the options Generate linker listing, Segment map, and Module map. If you have the ILINK linker, select the option Generate linker map file.

Now you should link the object file, to generate code that can be debugged.

3	Choose Project>Make. The progress will as usual be displayed in the Build messages window. The result of the linking is the code file project1.dxx with debug information located in the Debug\Exe directory and a map file project1.map located in the Debug\List directory.

Examine the file project1.map to see how the segment definitions and codesections were placed in memory.

Both XLINK and ILINK can generate extensive listings:

ILINK can generate a map file, which typically contains a placement summary. ILINK can also generate a log file, which logs decisions made by the linker regarding initializations, module sections, section select, etc.