Build Manager

Parent Previous Next

Build Manager

Introduction

One of the goals in the development of winIDEA was to achieve a tight integration of all stages of program development (edit, build and debug) by a single application.

winIDEA provides its own editor and powerful debugging capabilities, it lacks however an integrated compiler toolset. Instead, virtually any third party command line driven compiler, assembler and linker can be integrated to run as a part of winIDEA.

winIDEA provides several specialized objects that facilitate this integration. You will manage you project hierarchy in the Project Workspace Window, run compilers using the Project Toolbar and configure compiler options in the Project Settings dialog.

In addition winIDEA separates project configuration settings from workspace settings in a separate project configuration file. This file is generated automatically when the workspace file (.XJRF or .JRF) is generated. It carries the same name, however with a different extension (.XQRF or .QRF). This separation allows teams of developers to share the same copy of the .QRF file while every developer can customize his individual setting in the workspace file.

When using source code control and versioning systems (SourceSafe, PVCS, etc.) you will want to control the project (.QRF) file as well as your source files. Since the workspace file (.JRF) is user specific, it should not be shared.

Note: If you copy the workspace file (.JRF) to a new directory, always copy the project configuration file (.QRF) too, otherwise you will have no project settings when you open the workspace file in the new location.


Note: In winIDEA versions earlier than 8.5, the project configuration file had a .PRF extension. This file is read by newer versions, but changes are saved to the new QRF format.

Detecting Changes to the Project

When the build manager is configured properly, it will check all project files and recompile/assemble those where:

the objet file doesn't exist

the object file is older than the project file

any of the header files used by a C project file is newer than the object file

compiler/assembler settings for the project file have changed

A project will be linked (output file generated) when:

the output file doesn't exist

any of the object files is newer than existing output file

linker settings have changed

the indirection file has changed

This check is performed before the CPU operation is advanced (download, step, etc.).

In such case the below dialog will ask you whether the project should be rebuild.

The 'Project not up to date' dialog

Yes

Choose 'Yes' to rebuild the project.

No

If you choose 'No', the project will not be rebuilt and winIDEA will not prompt you again until the project is rebuilt explicitly.

Cancel

Choose 'Cancel' to abort the attempted operation. The project is not rebuilt.

Project Organization

winIDEA adds two hierarchical levels between the project and files that it consists of (project files). These two levels are an abstract organizational form, which you can use if you feel the need to, or not use at all - especially for small projects.

Project Workspace Window showing project hierarchy

Directory Organization

It is strongly recommended that all workspace and project related files are placed in the workspace directory or one of its sub-directories. The figure below illustrates a small project.

Typical Directory Organization

You can see the workspace file (ACTIVE_GT.xjrf) along with a matching project configuration file (ACTIVE_GT.xqrf).

All project files (CPUTest.c, main.c, …) and some header files are located in the same directory. For larger projects you will usually want to place project files in sub-directories whose names resemble group names, but this is entirely your choice.

The Debug sub-directory contains files generated by processing project files when the 'Debug' target is selected. This includes object, listing, map, absolute object, symbol files, etc. in short everything that can be regenerated every time. The Release sub-directory holds the same set of files, only this time they are generated by selecting the 'Release' target.

This separation of source and output files keeps your source directories clean and brings additional advantages as described next.

Targets

A project can have one or more Targets.

A Target controls all project files by defining default command line options for newly added project files, and by defining an Output Directory for all intermediate files generated in compile, assemble and link process.

Targets dialog

Before inserting any project files in the project, you should review and modify the target settings in the Project Settings dialog.

Note: Target settings are shown, and can be edited when target’s name is selected in the tree view of the project.

Every project file that you insert in the project will assume these target settings.

Later on, if you decide to modify targets settings, open the Project Settings dialog, select the desired Target and configure new Target settings.

Review command line settings for compiler and assembler

Use the 'Reset…' button

To apply Target settings to all project files - by doing so, you reset settings for every project file (including those, whose settings have been set explicitly) to current Target settings.


Use the 'Set Default…' button

To discard current Target settings and return to winIDEA's hard coded default settings - by doing so you will change Target settings - which will apply to newly added project files and to existing project files whose settings, have not been explicitly set (see below).

Why Would You Want to Use More than One Target

In course of development you will sometimes wish to maintain a version that is easy to debug (debug info, no optimizations, conditionally compiled debugging aid code), and a version that you release in the finished product (no debug info, full optimization, no unnecessary code, etc.).

Traditionally, you would work with so called 'Debug' settings when generating debuggable code. When you wished to create a 'Release' version, you would change all settings and make a full build of your project. This is inconvenient because:

it takes quite a while to make a full build of a large project

if some files need special compiler settings (disable debugging in certain modules etc.), you must take special care in defining settings for these files every time you change 'global' settings.

you then need to do this all again to return settings back to 'Debug mode'

winIDEA's Build Manager solves this

by maintaining settings for all configured targets, not just the current one - so you have to define them only once

by keeping intermediate files (object, listing) in a separate Output directory - that is different for every Target. Besides keeping your source directories clean, this assures that object files located in 'Debug' target directory are compiled with Debug settings and object files in 'Release' target directory with Release settings.
Hence, rebuilds are not necessary. When switching Targets you only perform a 'Make'.

Adding a Target

Note: When a new project is created, a Target named 'Debug' is generated automatically.

Open the Targets dialog in the Project menu.

Select the ‘New’ button

In the 'New Target' dialog specify the name for the new target and choose whether default options should be used, or target settings copied from an existing target.

New Target dialog

Select OK button to finish

Note: when copying settings from an existing target, only target settings are copied - not for every individual project file. Files with explicitly set settings assume Target options in the new target. If you need to, you must configure them manually.

Renaming a Target

To rename a target click the ‘Rename’ button in the Project/Targets dialog, and Specify the ‘New Target Name’ for the target.

Rename Target dialog

Groups

A Group is a collection of project files. Every Group exists in every target and groups the same project files. Besides being a visual aid in browsing project hierarchy, group names can be used in the link process.

What Groups don't have, are compilation and assembly settings, output directories, etc.

Why would You Want to Use More than One Group

If you wish to enforce link order of an object file or group of object files, the easiest way to do it is to define as many groups (with descriptive names) as necessary. For a banked system, for example, such names could be ‘Common’, ‘Vectors’, ‘Bank 1’ and ‘Bank 2’, but also ‘Jack's files’, ‘Nancy's files’ etc.

When a hundred or more project files are used, you will find it hard to find them in the Project Workspace window. By organizing them in groups (again with descriptive names) you will find them much faster.

Adding a Group

Open the Context menu of the Project Workspace Window

Select the 'Add Group…' command

Enter then name for the new group when prompted for it

Select the OK button to finish

Project Files

Project files are the meat of your project. By compiling, assembling and linking them, your project is built.

winIDEA divides project files by their extension into four types:

compiler source files (typically .C extension)

assembler source files (sometimes .ASM, but also .A51, .S07, …)

object and library files (.OBJ, but also .H11, .R03…)

files that do not take part in the build process - text files, graphics - anything that you find handy to have available by mouse click in the Project Workspace Window.

Configuring Project Files

Select the 'Project Files…' command from the Project menu

In the Project Files dialog, select the files you wish to add, and the group you wish to add them to.

Select the OK button to finish.

When a project file is inserted in the project, a set of settings for every existing target is generated for it. For every target, current target settings are used.

The Project Files dialog

Alternatively, you can add a file which is open in an editor, by selecting the 'Add to project' command from editor's local menu.


Link Order of Files and Groups

On certain occasions the project's object and library files must be linked in specific order. The Build Manager will process groups and their project files in alphabetical order unless specified differently in the link order dialog.

Link Order dialog

To open the link order dialog:

select the target in the project workspace window

right-click it to open the context menu

select the ‘Change Link Order’ command

Build Manager passes groups to the linker as they are listed in the Group list. You can change the ordering of groups by selecting a group and moving it up and down in the list with the arrow buttons right of the list.

Inside a group, project files are processed as they are listed in the Files list.

Compiler Tool-set Integration

To take maximum advantage of winIDEA's Build Manager, numerous settings must be configured properly. winIDEA ships with ready-made example projects for all major compilers, which you can use as template workspaces for your new projects.

For quick starts and small projects, you can use an example workspace as a template for your workspace, for bigger projects however you will want to have more control over the Build Manager's settings.

You have already learned how to add targets and groups, what remains is the Project Settings dialog, where global, target and project file specific settings can be configured.

Scope of Settings

Project settings can have one of following scopes:

Global scope - always valid (example: path to assembler EXE)

Target scope - valid when the respective target is selected
(example: Target's output directory)

File scope - valid when a file is being compiled or assembled
(example: compiler command line options)

Configuring Settings for Multiple Files

Settings for multiple files can be configured simultaneously. To do so:

expand the project hierarchy as needed

select project files, groups and targets that you wish to manipulate

configure settings that you wish all selected files to assume

In the figure below, settings for following files are being manipulated:

main.c in the 'Debug' target

All files in the 'Library Files' group in the 'Debug' target

All files in the 'Release' target

Setting options for multiple files simultaneously

In dialog pages where target and project file specific settings can be set, you will notice two buttons which are used to reset settings.

The 'Reset' button

Clicking on 'Reset' button will preset settings for currently selected files to current target settings. In previous example this means:

main.c in the 'Debug' target assumes current 'Debug' target settings

All files in the Library Files' group in the 'Debug' target assume current 'Debug' target settings

All files in the 'Release' target assume 'Release' target settings

In other words, selecting 'Reset' on any file or group of files, discards all settings that were defined explicitly (for a project file after it has been inserted into project).

The 'Set Default' button

The 'Set Default' is enabled only when a target is selected. Clicking it will cause the selected target to assume settings that are hard coded into winIDEA.

This will also affect settings of all project files in the target whose settings have not been changed explicitly.

General page

Project Settings dialog, General page

External Make File

When this option is checked the Build Manager will not attempt to build the project by itself but will rather call an external batch file - which you must specify. This batch file is now in charge of creating the absolute object file.

This option effectively disables the Build Manager. All make and build requests are routed to the external make file. It will however still detect modifications to either project or include files and invoke the external make file when necessary.

This setting has global scope.

Parameters

The string specified here will be passed to the external make file.

This setting has global scope.

Compiler toolset path

Compiler toolset path defines the directory where compiler, assembler, linker and companion files have been installed. Although you will see absolute paths to compiler, assembler and linker or to library files included in the project files list, all these paths are internally kept as relative to this directory. If you have different version of your compiler installed in different directories, you can easily switch amongst them just by changing this path.

This setting has global scope.

This option also accepts entries with environment variables enclosed in % signs.

Example:

The environment variable C_BASE is set to 'X:\C51'.

The entry in the 'compiler toolset path' option set to '%C_BASE%\BIN' would yield 'X:\C51\BIN'.

Root Directory

Specifies a root directory for project files location.

If this field is left blank the workspace directory is used as the root directory.

If this field is not blank, then winIDEA workspace is obviously irrelevant to the project configuration and keeping the relative path introduces a risk of failure if winIDEA workspace file is moved.


If Root directory is changed, project files locations can be adjusted

Project files paths are kept relative to the Project Root to allow movement of the project folder hierarchy. If Project Root directory is changed, project file location can be adjusted. winIDEA will prompt the user:


This setting has global scope.

This option also accepts entries with environment variables enclosed in % signs.

Example:

The environment variable C_BASE is set to 'X:\C51'.

The entry in the 'root directory' option set to '%C_BASE%\BIN' would yield 'X:\C51\BIN'.

Executable File

Defines the name of the file, which is generated at the end of the build process. This will usually be the final executable (absolute object file) generated by linker. This file must be known by the Build Manager to tell a successful build from an unsuccessful one.

Although you must specify only the name of the file (without any path specification), the file is always searched for in the current target's output directory.

This setting has global scope.

Executable Directory

Defines the directory where executable files are stored when the selected target is active.

This setting has target scope.

Intermediate files directory

Intermediate files directory option controls placement of temporary files generated during compile and assembler runs. If the option is checked, these will be put in the specified subdirectory of the Root directory.

If this option is not checked, the intermediate files will be placed into the Executable directory.

This setting has target scope.

Exclude File from Make

When this option is checked the selected file will not be processed by any of the translation tools, no matter what type it is.

This setting has file scope.

Error Filter

Defines the method by which output emitted by translation tools (compiler, assembler and linker) is filtered to extract errors and warnings.

If your compiler is not supported, you can still view unfiltered output in the 'tools' pane of the output window.

This setting has global scope.

Advanced

Clicking this button configures advanced filter options.

The default settings in the advanced dialog are hard coded in the winIDEA for the currently selected filter.

Advanced filter options

You may change this options if no filter is available for you version of compiler.

Use default error file

If this option is checked, the default error file for the generated tool is used. This file can be either captured STDOUT or STDERR stream or a file with a standard named or extension.

This standard file is hard coded in winIDEA for the current filter.

Use Custom error file

Check this option to override the default error file. You can use macro names available by clicking the '>' button.

Use external filter

You can create and use an external set of filters.

Redirection

Some compiler/OS combinations will fail to work if the STDOUT is captured, or the STDOUT is fed to another stage in the compiling process. IF this is the case, this option will redirect only STDERR stream. Note that the STDOUT stream output will then not be visible in the Tools pane.



Includes

Project Settings, Includes page

Include Search Paths

The Include File Directories list holds a record of all directories that should be searched for include files. The include files are searched in directories in order of their appearance in ‘Includes search paths’ dialog. The order can be changed by pressing the ‘up’ or ‘down’ arrow.

If ‘Search subdirectories’ at a selected path is selected, also the subdirectories of this path are searched.

Note: these directories are used by the Build Manager to search for include files used by project files to determine whether an include file has changed, in which case the project file needs to be recompiled.
If the compiler itself requires include files path specification, you must provide this separately in the form that your compiler expects (environment variables, command line options, configuration files, etc.)

This setting has global scope.

Warn if include file is not found

This option toggles whether a warning is issued when an include file is found or not.

Compiler cmd. line prefix

Here you can specify a prefix (-I by default) for a compiler command line.

For every specified path a separate item preceded by this prefix will be put in the compiler command line.

Check Assembler Includes

Since there is no standard (like ANSI for C/C++) to define an include file for an assembler, the include syntax must be described manually.

If ‘Check assembler Includes’ is checked, assembler project files will be searched for includes

Require leading blanks

Check if the include directive must not start in the first column.

Allow leading blanks

Check if the include directive can start in any column, including the first.

Include Keyword

Specify the include directive keyword.

Path start char

Specify the character that immediately precedes the include file name.

Path end char

Specify the character that immediately follows the include file name.

The dialog will show an example of the current configuration in the ‘Example’ field.

Search also source file folder

If this option is set (default), then first the folder of the source file is checked before all listed includes search paths are checked. This is equivalent to C’s: #include “filename”

If this option is disabled, the source file folder is not checked and is equivalent to C’s #include <filename>

Note: always verify that the thus specified algorithm is the same as the assembler implements.


File Extensions page

The File Extensions page defines file extensions by which files handled by the Build Manager are identified.

Project Settings dialog, File Extensions page

All settings on this page have global scope.

For every build step the extra extensions indicate other types of files that can be generated in the process. A file that carries the same name and one of the extensions specified here is moved to the output directory along with the object file.
These types can be specified when the "Don't use time based build manager" option on the Customize page is selected.

Compiler extensions

These are the types of files that a standard C compiler deals with:

Input Ext. - winIDEA's project files (usually .C or .CPP). If more than one extension is possible, separate them with commas or semicolons.

Header Ext. - files included by project files
(usually .H)

Output Ext. – files generated by compiling a C file (usually .OBJ). If your compiler generates assembler source, specify the extension of generated assembler source files.

Extra Ext. – other file types, used with winIDEA. Files with this extension will be moved to target output directory along with the Output Ext. file.

Assembler extensions

For assembler the following extensions must be defined:

Input Ext. - winIDEA's project files. If more than one extension is possible, separate them with commas or semicolons.

Header Ext. - files included by assembler project files
(usually .INC)

Output Ext. – Object files generated by compiling an assembler file (usually .OBJ)

Extra Ext. – other file types, used with winIDEA. Files with this extension will be moved to target output directory along with the Output Ext. file.


Linker extensions

For the linker, only input extensions must be specified. These include object file extensions and library file extensions.

Extra Ext. – other file types, used with winIDEA. Files with this extension will be moved to target output directory along with the Output Ext. file.


Customize page

Customize page contains additional options for running translators.

All settings on this page have global scope.

Project Settings dialog, Customize page

Run After Linker

After link process successfully terminates, sometimes additional tools (object file converters, etc.) must be ran. If you need to run a tool or a batch file, specify its path and command line arguments here.

Beep when done

By default, winIDEA beeps after the build is done. With this option, the beep can be turned off.

Run translators with relative path

When checked, the translator is passed a relative path of the file(s) it requires for translation.
Otherwise absolute paths are used.

Copy output files to target directory

When checked, all files generated in process of translation (object, listing, etc.) are moved to current target's output directory.
Otherwise no files are moved.

Change working directory

When checked, the current (working) directory is changed to the directory of the file being processed.
This is required by some compilers.

Display tool parameters

Displays parameters passed to the tool.

Environment Settings

Some compilers require special environment variables that tell them where to search for include files, library files, etc. Traditionally you had to set these options with SET command in the AUTOEXEC.BAT file. You can still do it the old way, but you can also specify them in this field.

To set a variable X to value A, write

X=A

Note: you must not use the SET keyword when defining the variable.

You can use existing environment variables in new definitions. Following definition extends the PATH variable to include new path:

PATH=%PATH%;c:\C51

Run Before/After

Actions preceding make/build or following compile or assembly execution can be configured. In this case, select the 'Run Before/After' button.

Run Before/After dialog

Translator Execution

Clicking the 'Translator Execution…' will open the Advanced Translator Execution dialog, where you can define how individual tools are spawned and their output captured.

Run with command interpreter

When checked, the tool is not spawned directly, but rather with a command interpreter.

If the tool fails to start or its output cannot be captured with default settings, you may try changing this option.

In general the option should be checked when running under Windows NT and unchecked when running under Windows 9x.

If the compiler is installed in a path with blanks, this option must be cleared. If the compiler doesn’t operate in this case, the path must be renamed so it doesn’t contain blanks.

Capture translator output

When checked the STDOUT and STDERR streams are directed to a disk file which winIDEA later uses to filter out the error messages.

In general this option should be checked. The only cases are tools that expect input on the STDIN stream or send file output to the STDOUT stream. In such case this option should be unchecked (for such tools the error output is usually generated in a separate error file).

Advanced Translator execution options


Compiler page        

The compiler page contains options specific to the C compiler. If you are using only assembler, you do not need to set any options on this page.

Project Settings dialog, Compiler page

Compiler Path

Specifies the path to the compiler's EXE file.

This setting has global scope.

If you wish to call up a batch file, you can not specify its path directly, but must create an intermediate batch file that calls up your batch file.

If the compiler path is left blank, then the first argument in the 'Options' setting should be the translator path. This allows per file configuration of the used compiler (since, for example, some older ARM compilers provide a separate compiler for ARM and Thumb mode).

Example:

Files are compiled with COMPILE.BAT. To call it from winIDEA, create a new batch file COMPILE1.BAT containing:

CALL COMPILE.BAT %1

Specify COMPILE1.BAT as the path to the compiler. winIDEA will replace occurrences of  %1 in the batch file with options configured on the page.

Compiler Command Line Options

In this edit field you must enter command line options you wish the compiler to be called with when the selected file is compiled. These will usually be code generation options, conditional defines, etc.

Additionally macro entries are supported, available from the button on the right of the Options edit field. The simplest command line option will usually contain the macro for the file name being compiled:

$(EDNAME)

This macro will expand to the full file name at the time when the compiler is invoked.

This setting has file scope.

Run Assembler

When this option is checked, the Build Manager will run the assembler on the output file generated by compiler.

This setting has file scope.

Command Line Defines

In this option all command line defines, needed for the compiler to operate, can be specified.

Prefix/Postfix

The Prefix and Postfix are used when the $(DEFINES) macro is used. Every command line defines specified is completed with the value specified in the Prefix and Postfix options.

Argument file

Compiler can use parameters from an argument file. If this file contains winIDEA macros which should be resolved before compiler is called, specify this file here.


Assembler page

The assembler page contains options specific to the assembler. If you are using only compiler, you do not need to set any options on this page.

Project Settings dialog, Assembler page

Assembler Path

Specifies the path to the assembler's EXE file.

This setting has global scope.

If you wish to call up a batch file, you can not specify its path directly, but must create an intermediate batch file that calls up your batch file.

If the assembler path is left blank, then the first argument in the 'Options' setting should be the translator path. This allows per file configuration of the used assembler (since, for example, some older ARM assemblers provide a separate assembler for ARM and Thumb mode).

Example:

Files are compiled with ASSM.BAT. To call it from winIDEA, create a new batch file ASSM1.BAT containing:

CALL ASSM.BAT %1

Specify the ASSM1.BAT as the path to assembler. winIDEA will replace occurrences of %1 in the batch file with options configured on the page.

Assembler Command Line Options

In this edit field you must enter command line options you wish the assembler to be called with when the selected file is assembled. These will usually be code generation options, conditional defines, etc.

Additionally macro entries are supported, available from the button on the right of the Options edit field. The simplest command line option will usually contain the macro for the file name being assembled:

$(EDNAME)

This macro will expand to the full file name at the time that the assembler is invoked.

This setting has file scope.

Argument file

Assembler can use parameters from an argument file. If this file contains winIDEA macros which should be resolved before assembler is called, specify this file here.


Linker page

The linker page contains options specific to the linker.

All settings on this page have global scope.

Project Settings dialog, Linker Page

Linker Path

Specifies the path to the linker's EXE file.

If the linker path is left blank, then the first argument in the 'Options' setting should be the translator path. This allows per file configuration of the used linker (since, for example, some older ARM linkers provide a separate linker for ARM and Thumb mode).

Linker Command Line Options

In this field you must enter command line options you wish the linker to be called with. These will usually be only a path to the Indirection File with perhaps some additional options.

Link Order

Click this button to change the order in which object files are passed to the linker. See "

Link Order of Files and Groups" on page 10.

Skip object file existence check

If this option is checked, winIDEA will not check whether all linker input files (object, library) exist. By default, this option is off.

Linker Indirection File options

Due to large number of options that a linker must handle, most linkers can retrieve linkage options from an indirection file (also called command file, link file etc.).

Build Manager uses the indirection file to tell the linker which object and library files should be linked. It will search the indirection file for occurrence of translation characters, and replace them with a list of object files generated from the project files list.

The following features and rules apply to creating indirection files that can be used by winIDEA:

All occurrences of %1 are replaced with options specified in the Linker Command Line Options field

All occurrences of %2 are replaced with the name of the final output file (see “Executable File” on page 15).

Occurrences of translate characters are replaced with the names of object files.

All these conversions do not have any influence on the original indirection file. From it a new file is generated and the linker is given this file as the indirection file. When the linker finishes, this file is erased. The location, where this file is generated, is specified in the ‘Generate Replacement in’ option.

Generate replacement in

The replacement file for the Linker Indirection file will be generated in the location, specified here. The available locations are:

the same directory : creates the replacement indirection file in the same directory as the original indirection file. This option is the default and recommended as it allows the indirection file to contain references to other files in relative form.

Project Root directory : creates the replacement indirection file in the Project Root directory

Target Exec directory : creates the replacement indirection file in the current target's Exec directory. Note: this was default location in winIDEA 2005 and earlier.


Indirection file can be simply accessed via ‘Edit’ button.

Translation Character

When the translation character ('&' default) is encountered in the indirection file the Build Manager replaces it with the names of object files derived from the project files list.

There must always be at least two translation characters. The string of characters that they embed is used as the delimiter between object files:

Example:

If project files are TST1.C, TST2.C, TST3.C and LIBRARY.LIB, then

&,&

expands to

TST1.OBJ,TST2.OBJ,TST3.OBJ,LIBRARY.LIB

If you check the 'CR-LF After File Name' option, then every object/library file name will be written in a new line:

For the previous example:

TST1.OBJ,
TST2.OBJ,
TST3.OBJ,
LIBRARY.LIB

If more than two translation characters occur, the following syntax applies:

&<prefix>&<delimiter>&<postfix>&<group>&

For each project file <prefix> will be put before the file name, and <postfix> behind the name. Project files will be delimited with <delimiter>.

If a group (see "Groups" on page 8) is specified, then only project files that belong to the specified group are inserted at that position.

If in the previous example LIBRARY.LIB and TST1.C belong to group 'COMMON' and TST2 and TST3 to group 'BANK1' then following code:

BASE 0
&load &&&COMMON&
BASE 8192
&load &&&BANK1&

generates:

BASE 0
load LIBRARY.LIB
load TST1.OBJ
BASE 8192
load TST2.OBJ
load TST3.OBJ

The Build Manager will keep a record of which groups have already been written, so if a translation character sequence without group specification is found, the object files of all remaining groups are written in that place.

Here is a summary of how fields between translation characters will be interpreted for different numbers of translation characters:

        &<delimiter>&
&<prefix>&<delimiter>&
&<prefix>&<delimiter>&<postfix>&
&<prefix>&<delimiter>&<postfix>&<group>&

Note: The placement of tags in the indirection file takes precedence over link order settings.

Path separator

This character is used in the indirection file to construct a full path to an object file. Most linkers understand the backslash '\', but others expect a forward slash '/'.

Build Page

The build page contains options related to build operations.

All settings on this page have global scope.

Project Settings dialog, Build page

Settings on this page allow you to specify how Project/Make and Project/Rebuild operations are performed.


Internal (default) - uses winIDEA’s integrated make utility. In case of Make command, all project files that are out of date are recompiled and finally linked. In case of Rebuild, all project files are recompiled and linked.

External – the specified executable is invoked. It is the responsibility of this executable to perform the requested operation.

Note: Unlike General/Use External Make which invokes the external make utility after winIDEA identified one or more files being outdated, these tools are ran unconditionally.


Build Manager Macros

Whenever defining command line options, build manager macros can be used. The macro list is invoked by pressing the button. The macros that are normally used for the option you are defining command line for are shown.

Build Manager Macros selection

The selected macro is translated to a simple note in the command line, which will be translated to the selected option. For example, the macro selected above, 'Compiler output extension' would translate to $(COUTEXT), which would translate when generating the command line option to, for example, OUT, which is the compiler output file extension.

Available Build Manager Macros and their descriptions

The macros listed here are marked by the macro name, its verbose name as it appears when pressing the   button, and their description.


$(CMPDIR)/Compiler directory

Path specified in the 'Project/Settings/General/Compiler toolset path'


$(IRFDIR)/Workspace directory

The Project root directory


$(WSPNAME)/Workspace name

The Project name


$(EXEDIR)/winIDEA directory

The directory where winIDEA.exe is located


$(EDNAME)/Full file name

The file name of the file currently compiled/assembled



$(DIR)/Directory of file

The directory of the file currently compiled/assembled


$(NOEXT)/File name

The file name of the file currently compiled/assembled, without file extension


$(OUTPUTFILE)/Output file name

The name specified in 'Project/Settings/General/Output file name'


$(OUTPUTDIR)/Target output directory

Current target output directory as specified in 'Project/Settings/General/Output directory'


$(OUTPUTPATH)/Output file path (Full)

Current target output directory as specified in 'Project/Settings/General/Output directory' in full path form.


$(OUTPUTNOEXT)/Output file path without extension

The name with path specified in 'Project/Settings/General/Output file name', without file extension


$(OUTPUTNAME)/Output file name without extension

The file name specified in 'Project/Settings/General/Output file name', without file extension


$(CEXT)

File extension specified in 'Project/Settings/File Extensions/Compiler/Input

Ext'.


$(COUTEXT)/Compiler Output Extension

File extension specified in 'Project/Settings/File Extensions/Compiler/Output Ext'.


$(AEXT)

File extension specified in 'Project/Settings/File Extensions/Assembler/Input Ext'.


$(AOUTEXT)/Assembler Output Extension

File extension specified in 'Project/Settings/File Extensions/Assembler/Output Ext'.


$(FILEGROUP)/File Group Name

The name of the Group to which the currently compiled/assembled file belongs.


$(INDPATH)/Indirection File Path

Expands the full path of the indirection file name.


$(DEFINES)/Defines

The list of defines parsed to the C preprocessor.


$(INCLUDES)/Includes

The list of include files specified in the Includes tab.



Using an Example Workspace as a Template

You can make a quick start by modifying one of the example projects for the compiler that you use as follows:

Use Windows Explorer to create a new directory for the new workspace

Copy workspace (.XJRF) and project configuration (.XQRF) files from the example project directory. You can rename them if you wish, just make sure that .XJRF and .XQRF extensions remain and that the names are the same.

Copy any project files you wish to include in your project from the example directory. This could be startup files, interrupt function examples, etc.

Open the newly copied workspace in winIDEA.

Remove unused example project files from the project files list

Add your project files to the project files list

Select the Build command to rebuild the entire project

Build Session

When the Build Manager processes a project file or links the project it creates a child process with redirected standard handles (STDOUT and STDERR). The child process runs in a hidden window, so you do not get to see it while it runs. Any captured output is displayed in the Output window after the process ends.

Output Window

The Output Window is a scrollable, terminal style window that shows raw or filtered output emitted by external tools spawned by winIDEA.

Build Pane

The Build pane displays build progress and compiler, assembler and linker output filtered by respective filter programs. If no filters have been configured, only build progress and unsuccessful generation of expected output file is displayed.

Output Window, Build Pane

In above figure the highlighted line is a filtered error message. By double clicking on it, the source file of the error is opened and positioned to the location of the error.

If no filter was configured for the compiler all lines but this one would have been displayed.

Tools Pane

The 'Tools' pane displays all output emitted to standard output (STDOUT) and standard error (STDERR) by any external tool, including build tools. No filtering occurs.

Output Window, Tools pane

In above figure, error messages were emitted to STDOUT, you can review them but no automatic error source tracking is available.

Note: tools output is captured only when the  'Capture Translator Output' ("Customize Page" on page 22) option is checked.

Building

winIDEA's Build Manager can build on demand (compile or assemble) a single project file, all modified project files (make) or all project files (rebuild).

Building a Single Project File

Open the project file that you wish to build

Write any desired changes to the source

    Compile button

Select 'Compile/Assemble' command from the context menu, from the Project menu or click the Compile button on the Project toolbar.

alternatively you can:

Select a file in the Project Workspace window

Select the 'Compile/Assemble' command from the context menu

Building All Modified Project Files

This is probably the build command you will be using most, since Build Manager automatically detects which files need to be built and performs all necessary actions to get the project up to date.

To build all modified project files

Select the 'Make' command from the Project menu

or

    Make button

Click the Make button on the Project toolbar

Building All Project Files

On certain occasions, such as when you upgrade your compiler or suspect that the 'Make' didn't get the project built OK, you can instruct the Build Manager to build all project files unconditionally.

To build all project files

Select the 'Rebuild' command from the Project menu

or

    Rebuild button

Click the Rebuild button on the Project toolbar

Breaking the Build

winIDEA's Build Manager performs all actions in background, so you are free to continue with your work while build is in progress. If for some reason you wish to abort building

Select the 'Stop Build' command from the Project menu

or

  Stop Build button

Click the Stop Build button on the Project toolbar.