Creating and using libraries

This tutorial demonstrates how to create a library project and how you can combine it with an application project.

If you are working on a large project, you will soon accumulate a collection of useful modules that contain one or more routines to be used by several of your applications. To avoid having to assemble or compile a module each time it is needed, you can store such modules as object files, that is, assembled or compiled but not linked.

You can collect many modules in a single object file which then is referred to as a library. It is recommended that you use library files to create collections of related routines, such as a device driver.

If your product package includes the XLINK linker, use the IAR XAR Library Builder to build libraries, and if your product package includes the ILINK linker, use the IAR Archive Tool iarchive to build libraries.

The Main.sxx or Main.s program uses a routine called max to set the contents of one register to the maximum value of two other registers. The EXTERN directive declares max as an external symbol, to be resolved at link time.

The two library routines will form a separately assembled library. It consists of the max routine called by main, and a corresponding min routine, both of which operate on the contents of the registers used in the Main.sxx or Main.s program. The Maxmin.sxx file contains these library routines and a copy is provided in the cpuname\tutor directory.

The routines are defined as library modules by the MODULE directive (XLINK only), which instructs the IAR XLINK Linker to include the modules only if they are referenced by another module.

The PUBLIC directive makes the max and min symbols public to other modules.

For detailed information about the MODULE and PUBLIC directives, see the IAR Assembler Reference Guide.

1	In the workspace tutorials used in previous chapters, add a new project called project5.

2	Add the file Main.sxx or Main.s to the new project.

3	To set options, choose Project>Options. Select the General Options category and click the Library Configuration tab. Choose None from the Library drop-down list, which means that a standard C/C++ library will not be linked.

4	To assemble the file Main.sxx or Main.s, choose Project>Compile.

1	In the same workspace tutorials, add a new project called tutor_library.

2	Add the file Maxmin.sxx to the project.

3	To set options, choose Project>Options. In the General Options category, verify these settings:

Page	Option
Output	Output file: Library
Library Configuration	Library: None

Note that Library Builder appears in the list of categories, which means that the IAR XAR Library Builder (for XLINK) or IAR Archive Tool iarchive (for ILINK) is added to the build toolchain. You do not have to set any specific options specific for library building for this tutorial.

4	Choose Project>Make.

The library output file tutor_library.rxx has now been created in the projects\Debug\Exe directory.

1	In the Workspace window, click the project5 tab. Choose Project>Add Files and add the file tutor_library.rxx (tutor_library.a for ILINK) located in the projects\Debug\Exe directory. Click Open.

2	Click Make to build your project.

You have now combined a library with an executable project, and the application is ready to be executed. For information about how to manipulate the library, see the IAR Linker and Library Tools Reference Guide if you built the library using XAR and IAR Archive Tool documentation available in the IAR C/C++ Development Guide if you built the library using iarchive.