Building from the command line

Introduction

This Technical Note provides an example of how to build a project without using the IAR Embedded Workbench IDE.

Discussion

The alternatives below are examples made for IAR Embedded Workbench for Arm, but they can easily be modified for other target devices.

Alternative 1: Use the IAR Command Line Build Utility

For a project file (myProject.ewp) with a build configuration (myConfig), the following command can be used to build the project:

install-dir/common/bin/iarbuild myProject.ewp myConfig

To rebuild the project and log all messages generated from the build, use the following command:

install-dir/common/bin/iarbuild myProject.ewp -build myConfig -log all

Note:

• The -build command corresponds to two executions of the tool, first a run with the option -clean and a second run with the option -make.
• You can run iarbuild.exe without any parameters to get usage information.

Alternative 2: Build (compile and link) from the command line

Overview

To build an executable file without using iarbuild, first compile and assemble the source files and then link them using the linker.

• If the project has assembler source files, use the IAR Assembler for the target architecture (arch):

install-dir/arch/bin/iasmarch source_file options

• Compile each C/C++ source file using the IAR C/C++ Compiler for the target architecture (arch):

install-dir/arch/bin/iccarch source_file options

• Link all the application's object files and libraries to an executable file.
  • Linking with the IAR ILINK Linker:

install-dir/arch/bin/ilinkarch obj1.o obj2.o ... options -o myApp.out

• • Linking with the IAR XLINK Linker:

install-dir/arch/bin/xlink obj1.rnn obj2.rnn ... objN.rnn lib1.rnn lib2.rnn ... libN.rnn options -o myApp.dnn

Collecting information from the Build window to be used on the command line

Try the following to manually create a shell script, that builds a project using the same build commands as in the IDE.

1. Add the following options in the Project>Options dialog box in the IDE:

• C/C++ Compiler>Extra Options: --silent
• Assembler>Extra Options: -S
• Linker>Extra Options: --silent

2. Choose View>Messages>Build in the IDE to open the Build window. By default, the messages you need are filtered out, so right-click to open the context menu and select Live Log to File>Filter Level>All.

3. Also from the context menu, select Enable Live Logging to the file BuildLog.log. (The default location is in the project directory.)

4. Build the project. Once the project is built, the BuildLog.log file holds the sequence of build commands.

5. Make a copy of BuildLog.log and rename it. Change the filename extension of the copy to use a suitable script extension (for example, build.bat or build.cmd in Windows, build.sh in Linux, etc.) and open the file in a text editor.

6. The script file requires some modifications to execute properly. Modify the following:

• Remove lines that only consist of filenames.
  • For editors that support regular expressions, remove content that matches the following:
    ^.*\.([Cc]([Xx][Xx]|[Pp][Pp])|[Cc][Cc]|[cC]|[sS]|[Aa][Ss][Mm]|out)$.
• For any build command that has stream redirector characters (in other words, < or >) in its parameters, such as iasmarch -M<> ...
  • Surround the parameter with quotes (iasmarch -M<> ...) so that the command can be executed correctly from the shell.
• Depending on the number of object files in the project, the linker command might exceed the shell’s command line maximum length (for example, 8192 characters for Windows Command Prompt). To avoid such a situation, use an extended command line file (.xcl):
  • Edit build.bat: cut all the parameters from the ilinkarch command and paste them to a linker configuration file (for example, linker-args.xcl).
  • Edit linker-args.xcl: insert a line break after each parameter.
  • Edit build.bat: change the ilinkarch line to ilinkarch -f linker-args.xcl.
• If you are creating a Linux shell script:
  • Change the paths to the corresponding build tools (for example, /opt/iarsystems/bxarch/arch/…).
  • Update the directory delimiters from backslash (\) to forward slash (/).
  • Make the script executable (that is, chmod +x build.sh).
• Remove any other trailing information that is irrelevant for the script to execute properly.

Conclusion

IAR Embedded Workbench projects can be directly built from the command line

• either in a single pass by using the IAR Command Line Build Utility (iarbuild) or
• by manually creating a shell script that compiles the sources and links them to a final executable file.

For more information, refer to the section Building from the command line in the IDE Project Management and Building Guide, available from the Help menu in the IAR Embedded Workbench IDE.

All product names are trademarks or registered trademarks of their respective owners.