4.3 Linker Options

Options in EDE versus options on the command line

Most command line options have an equivalent option in EDE but some options are only available on the command line. EDE invokes the linker via the control program. Therefore, it uses the syntax of the control program to pass options and files to the linker.

See section 4.4 , Control Program Options.

If necessary, you can specify a command line option in EDE.

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Enter one or more command line options in the Additional options field.

Be aware that some options are not useful in EDE or just will not have any effect. For example, the option -k keeps files after an error occurred. When you specify this option in EDE, it will have no effect because EDE always removes the output file after an error had occurred.

Short and long option names

Options can have both short and long names. Short option names always begin with a single minus (-) character, long option names always begin with two minus (--) characters. You can abbreviate long option names as long as it forms a unique name. You can mix short and long option names on the command line.

Options can have flags or suboptions. To switch a flag 'on', use a lowercase letter or a +longflag. To switch a flag off, use an uppercase letter or a -longflag. Separate longflags with commas. The following two invocations are equivalent:

When you do not specify an option, a default value may become active.

-?/-H (--help)

EDE

-

Command line syntax

Description

Displays an overview of all command line options.

Example

The following invocations all display a list of the available command line options:

Related information

-

--case-insensitive

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker/Locator entry and select Linker.

3. Disable the option Link case sensitive.

Command line syntax

Description

With this option you tell the linker to consider upper and lower case characters the same. By default the linker considers upper and lower case characters as different characters.

Disabling the option Link case sensitive in EDE is the same as specifying the option --case-insensitive on the command line.

Assembly source files that are generated by the compiler must always be assembled and thus linked case sensitive. When you have written your own assembly code and specified to assemble it case insensitive, you must also link the .o file case insensitive.

Example

To link case insensitive:

The linker considers upper and lower case characters as being the same. So, for example, the label LabelName is considered the same label as labelname.

Using the control program to pass the option directly to the linker:

Related information

Assembler option -c (Assemble case insensitive)

-c (--chip-format)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Output Format.

3. Enable one or more output formats.

Command line syntax

You can specify the following formats:

The addr_size specifies the size of the addresses in bytes (record length). For Intel Hex you can use the values: 1, 2 and 4 (default). For Motorola S you can specify: 2 (S1 records), 3 (S2 records, default) or 4 bytes (S3 records).

Description

With this option you specify the Intel Hex or Motorola S-record output format for loading into a PROM-programmer. The linker generates a file for each memory chip.

Use option -F (--format) to specify an absolute (debugging) output format.

Examples

Generate Intel Hex output files for each chip:

Related information

Linker option -F (output format) ,
Section 6.2, Motorola S-record Format,
Section 6.3, Intel Hex Record Format, in Chapter Object File Formats.

-D (--define)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Add the option -D to the Additional options field.

Command line syntax

Description

With this option you can define a macro and specify it to the linker preprocessor. If you only specify a macro name (no macro definition), the macro expands as '1'.

You can specify as many macros as you like: you can use the option -D multiple times. If the command line exceeds the limit of the operating system, you can define the macros in an option file which you then must specify to the linker with the option -ffile.

Define macro to the preprocessor, as in #define. Any number of symbols can be defined. The definition can be tested by the preprocessor with #if, #ifdef and #ifndef, for conditional locating.

Example

To define the RESET vector, interrupt table start address and trap table start address which is used in the linker script file tc1v1_3.lsl, enter:

Related information

Linker option -f (Name of invocation file)

-d (--lsl-file)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Script File.

3. Select Use standard description for selected derivative or select Use project specific processor description and specify a name.

Command line syntax

Description

With this option you specify a linker script file to the linker. If you do not specify this option, the linker does not use a script file. You can specify the existing file target.lsl or the name of a manually created linker script file. You can use this option multiple times. The linker processes the LSL files in the order in which they appear on the command line.

The linker script file contains vital information about the core for the locating phase of the linker. A linker script file is coded in LSL and contains the following types of information:

Example

To read linker script file information from file tc1v1_3.lsl:

Using the control program:

Related information

Chapter 7 , Linker Script Language.

--diag

EDE

1. In the Help menu, enable the option Show Help on Tool Errors.

2. In the Build tab of the Output window, double-click on an error or warning message.

Command line syntax

Optionally, you can use one of the following display formats (format):

Description

With this option the linker displays a description and explanation of the specified error message(s) on stdout (usually the screen). The linker does not process any files.

If you want the output in a file, you have to use output redirection.

Example

To display an explanation of message number 104, enter:

This results in the following message and explanation:

To write an explanation of all errors and warnings in HTML format to file lerrors.html, enter:

Related information

Section 7.9 , Assembler Error Messages, in Chapter Using the Linker of the User's Guide.

-e (--extern)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Add the option -e in the Additional options field.

Command line syntax

Description

With this option you force the linker to consider the given symbol as an undefined reference. The linker tries to resolve this symbol by extracting the corresponding symbol definition from a library. If the symbol is defined in an object file, this option has no influence on the link process.

Suppose you are linking from a library. Because the library itself already has been compiled and assembled, the linker does not find any unresolved symbols. Hence, the linker will not extract any module from the library. When you force a symbol to be undefined, the linker extracts those modules that contain the symbol.

This option is, for example, useful if the startup code is part of a library. Because your own application does not refer to the startup code, you can force the startup code to be extracted by specifying the symbol _START as an unresolved external.

Example:

Consider the following invocation:

Nothing is linked and no output file will be produced, because there are no unresolved symbols when the linker searches through mylib.a.

In this case the linker searches for the symbol _START in the library and (if found) extracts the object that contains _START, the startup code. If this module contains new unresolved symbols, the linker looks again in mylib.a. This process repeats until no new unresolved symbols are found.

Related information

Section 7.4.1 , Specifying Libraries to the Linker, in Chapter Using the Linker of the User's Guide.

--error-file

EDE

-

Command line syntax

Description

With this option the linker redirects error messages to a file.

If you do not specify a filename, the error file is task1.elk.

Example

The linker writes error messages to the file my.elk instead of stderr.

Related information

Linker option --warnings-as-errors (Treat warnings as error)

-F (--format)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Output Format.

3. Enable one or more output formats.

Command line syntax

You can specify the following formats:

Description

With this option you specify the output format for the resulting (absolute) object file. The default output format is ELF/DWARF, which can directly be used by the CrossView Pro debugger.

Use option -c (--chip-format) to create Intel Hex or Motorola S-record output files for loading into a PROM-programmer.

Examples

Generate ELF/DWARF output file:

Related information

Linker option --chip-format (Hex files per chip)
Section 6.1, ELF/DWARF Object Format, in Chapter Object File Formats.

-f (--option-file)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Add the option -f to the Additional options field.


In EDE you can save your options in a file and restore them to call the linker with those options:

1. From the Project menu, select Save Options... or Load Options...

Be aware that when you specify the option -f in the Additional options field, the options are added to the linker options you have set in the Project Options dialog. Only in extraordinary cases you may want to use them in combination.

Command line syntax

Description

Instead of typing all options on the command line, you can create an option file which contains all options and files you want to specify. With this option you specify the option file to the linker.

Use an option file when the length of the command line would exceed the limits of the operating system, or just to store options and save typing.

You can specify the option -f multiple times.

Format of an option file

     "This has a single quote ' embedded"
     'This has a double quote " embedded'
     'This has a double quote " and \
     a single quote '"' embedded"
     "This is a continuation \
     line"
          -> "This is a continuation line"

Example

Suppose the file myoptions contains the following lines:

Specify the option file to the linker:

This is equivalent to the following command line:

Related information

-

--first-library first

EDE

-

Command line syntax

Description

When the linker processes a library it searches for symbols that are referenced by the objects and libraries processed so far. If the library contains a definition for an unresolved reference the linker extracts the object that contains the definition from the library.

By default the linker processes object files and libraries in the order in which they appear at the command line. If you specify the option --first-library-first the linker always tries to take the symbol definition from the library that appears first on the command line before scanning subsequent libraries.

This is for example useful when you are working with a newer version of a library that partially overlaps the older version. Because they do not contain exactly the same functions, you have to link them both. However, when a function is present in both libraries, you may want the linker to extract the most recent function.

With this option, you tell the linker to scan the libraries from left to right, and extract the symbol from the first library where the linker finds it.

Example:

If the file test.o calls a function which is both present in a.a and b.a, normally the function in b.a would be extracted. With this option the linker first tries to extract the symbol from the first library a.a.

Related information

Linker option --no-rescan (Do not rescan libraries)

-k (--keep-output-files)

EDE

EDE always removes the output files when errors occurred.

Command line syntax

Description

If an error occurs during linking, the resulting output file may be incomplete or incorrect. With this option you keep the generated output files when an error occurs.

By default the linker removes the generated output files when an error occurs. This is useful when you use the make utility mktc. If the erroneous files are not removed, the make utility may process corrupt files on a subsequent invocation.

Use this option when you still want to use the generated file. For example when you know that the error(s) do not result in a corrupt output file, or when you want to inspect the output file, or send it to Altium support.

Example

When an error occurs during linking, the generated output file test.elf will not be removed.

Related information

-

-L (--library-directory / --ignore-default-library-path)

EDE

1. From the Project menu, select Directories...

2. Add a pathname in the Library Files Path field.

3. In the Library Files Path field, add the pathnames of the directories where the linker should look for library files.

Command line syntax

Description

With this option you can specify the path(s) where your system libraries, specified with the -l option, are located. If you want to specify multiple paths, use the option -L for each separate path.

By default path this is $(PRODDIR)\ctc\lib directory.

If you specify only -L (without a pathname) or the long option --ignore-default-library-path, the linker will not search the default path and also not in the paths specified in the environment variable LIBTC1V1_2, LIBTC1V1_3 or LIBTC2. So, the linker ignores steps 2, 3 and 4 as listed below.

The priority order in which the linker searches for system libraries specified with the -l option is:

1. The path that is specified with the -L option.

2. The path that is specified in the environment variable LIBTC1V1_2, LIBTC1V1_3 or LIBTC2 when the product was installed.

3. The default directory c:\ctc\lib.

4. The processor specific directory, for example c:\ctc\lib\tc1.

Example

Suppose you call the linker as follows:

First the linker looks in the directory c:\mylibs for library libc.a (this option).

If it does not find the requested libraries, it looks in the directory that is set with the environment variable LIBTC1V1_2, LIBTC1V1_3 or LIBTC2.

Then the linker looks in the default directory c:\ctc\lib for libraries.

Related information

Linker option -l (Link system library)

Section 7.4.2, How the Linker Searches Libraries, in Chapter Using the Linker of the User's Guide.

Section 1.3.2, Configuring the Command Line Environment, in Chapter Software Installation of the User's Guide.

-l (--library)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Libraries.

3. Enable the option Link default C libraries.

Command line syntax

Description

With this option you tell the linker to search also in system library libname.a, where name is a string. The linker first searches for system libraries in any directories specified with -L path, then in the directories specified with the environment variable LIBTC1V1_2, LIBTC1V1_3 or LIBTC2, unless you used the option -L without a directory.

If you use the libc.a library, you must always link the libfp.a library as well. Remember that the order of the specified libraries is important!

Example

To search in the system library libfp.a (floating-point library):

The linker links the file test.o and first looks in mylib.a (in the current directory only), then in the system library libfp.a to resolve unresolved symbols.

Related information

Linker option -L (Additional search path for system libraries)

Section 7.4.1, Specifying Libraries to the Linker, in Chapter Using the Linker of the User's Guide.

--link-only

EDE

-

Command line syntax

Description

With this option you suppress the locating phase. The linker stops after linking. The linker complains if any unresolved references are left.

Example:

The linker checks for unresolved symbols and creates the file hello.out.

Using the control program:

Related information

Control program option -cl (Stop after linking)

--lsl-check

EDE

-

Command line syntax

Description

With this option the linker just checks the syntax of the LSL file(s) and exits. No linking or locating is performed.

Example:

To check the LSL file(s) and exit:

Related information

Linker option -d (Linker script file)

Linker option --lsl-dump (Dump LSL info)

--lsl-dump

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Enable the option Dump processor and memory info from LSL file.

Command line syntax

Description

With this option you tell the linker to dump the LSL part of the map file in a separate file, independent of the -M (generate map file) option. If you do not specify a filename, the file ltc.ldf is used.

Example

The linker dumps the processor and memory info from the LSL file in the file mydump.ldf.

Related information

Linker option -m (Map file formatting options)

-M (--map-file)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Map File.

3. Enable the option Generate a map file (.map).

Command line syntax

Description

With this option you tell the linker to generate a linker map file. If you do not specify a filename, the linker uses the same basename as the output file with the extension .map.

A linker map file is a text file that shows how the linker has mapped the sections and symbols from the various object files (.o) to the linked object file. A locate part shows the absolute position of each section. External symbols are listed per space with their absolute address, both sorted on symbol and sorted on address.

With the option -m (map file formatting) you can specify which parts you want to place in the map file.

Example

To generate a map file (test.map):

The control program by default tells the linker to generate a map file.

Related information

Linker option -m (Map file formatting options)

Section 5.2, Linker Map File Format, in Chapter List File Formats.

-m (--map-file-format)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Map File.

3. Enable the options to include that information in the map file.

Command line syntax

You can set the following flags:

Default

Description

With this option you specify which information you want to include in the map file. Use this option in combination with the option - M (--map-file).

If you do not specify this option, the linker uses the default: -mCfklMORS.

Example

The linker generates the map file test.map that includes all default information plus the cross reference part, but not the processed files part.

Related information

Linker option -M (Generate map file)

Section 5.2, Linker Map File Format, in Chapter List File Formats.

--misra-c-report

EDE

1. From the Project menu, select Project Options...

2. Expand the C Compiler entry and select MISRA C.

3. Select a MISRA C configuration.

4. Enable the option Produce a MISRA C report.

Command line syntax

Description

With this option you tell the linker to create a MISRA C Quality Assurance report. This report lists the various modules in the project with the respective MISRA C settings at the time of compilation. If you do not specify a filename, the file name.mcr is used.

Example

The linker creates a MISRA C report file test.mcr.

Related information

Compiler option --misrac

-N (--no-rom-copy)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Add the option -N to the Additional options field.

Command line syntax

Description

With this option the linker will not generate a ROM copy for data sections. A copy table is generated and contains entries to clear BSS section. However, no entries to copy data sections from ROM to RAM are placed in the copy table.

The data sections are initialized when the application is downloaded. The data sections are not re-initialized when the application is restarted.

Example

The linker does not generate a copy table.

Related information

-

--no-rescan

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Libraries.

3. Disable the option Rescan libraries to solve unresolved externals.

Command line syntax

Description

When the linker processes a library it searches for symbol definitions that are referenced by the objects and libraries processed so far. If the library contains a definition for an unresolved reference the linker extracts the object that contains the definition from the library. The linker processes object files and libraries in the order in which they appear at the command line.

When all objects and libraries are processed the linker checks if there are unresolved symbols left. If so, the default behavior of the linker is to rescan all libraries in the order given at the command line. The linker stops rescanning the libraries when all symbols are resolved, or when the linker could not resolve any symbol(s) during the rescan off all libraries. Notice that resolving one symbol may introduce new unresolved symbols.

With this option, you tell the linker to scan the object files and libraries only once. When the linker has not resolved all symbols after the first scan, it reports which symbols are still unresolved. This option is useful if you are building your own libraries. The libraries are most efficiently organized if the linker needs only one pass to resolve all symbols.

Example:

To scan the libraries only once:

The linker resolves all unresolved symbols while scanning the object files and libraries and reports all remaining unresolved symbols after this scan.

Related information

Linker option --first-library-first (Scan libraries in the specified order)

--non-romable

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Add the option to the Additional options field.

Command line syntax

Description

With this option you tell the linker that the application is not romable. The linker will locate all ROM sections in RAM. A copy table is generated and is located in RAM. When the application is started, that data and BSS sections are re-initialized.

Example

The linker locates all ROM sections in RAM.

Related information

-

-O (--optimize)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Optimization.

3. Enable or disable the optimization suboptions.

Command line syntax

You can set the following flags:

Use the following options for predefined sets of flags:

Default

Description

With this option you can control the level of optimization. If you do not use this option, -OLt is the default.

Example

The following invocations are equivalent and result all in the default optimizations.

Related information

Section 7.2.3 , Linker Optimizations, in Chapter Using the Linker of the User's Guide.

-o (--output-file)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Add the option -o in the Additional options field.

Command line syntax

Description

By default, the linker generates the file task1.elf.

With this option you specify another name for the linker output file.

EDE and the control program name the output file always after the first input file with the extension .elf.

Example

To create the output file test.elf instead of task1.elf:

Related information

-

-r (--incremental)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Add the option -r in the Additional options field.

Command line syntax

Description

Normally the linker links and locates the specified object files. With this option you tell the linker only to link the specified files. The linker creates a linker output file .out. You then can link this file again with other object files until you have reached the final linker output file that is ready for locating.

In the last pass, you call the linker without this option with the final linker output file .out. The linker will now locate the file.

Example

In this example, the files test1.o, test2.o and test3.o are incrementally linked:

Related information

Section 7.5 , Incremental Linking, in Chapter Using the Linker of the User's Guide.

-S (--strip-debug)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Enable the options to include that information in the map file.

4. Disable the option Include symbolic debug information.

Command line syntax

Description

With this option you specify not to include symbolic debug information in the resulting output file.

Example

The linker generates the object file test.elf without symbolic debug information.

Related information

Linker option -M (Generate map file)

-V (--version)

EDE

-

Command line syntax

Description

Display version information. The linker ignores all other options or input files.

Example

The linker does not link any files but displays the following version information:

Related information

-

-v (--verbose)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Miscellaneous.

3. Enable the option Print the name of each file as it is processed.

Command line syntax

Description

With this option you put the linker in verbose mode. The linker prints the filenames and the link passes while it processes the files. It also shows which objects are extracted from libraries. With this option you can monitor the current status of the linker.

Example

The linker links the file test.o and displays the steps it performs.

Related information

-

-w (--no-warnings)

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Warnings.

3. Enable one of the options Report all warnings, Suppress all warnings, or Suppress specific warnings.

4. Enter the numbers, separated by commas, of the warnings you want to suppress.

Command line syntax

Description

With this option you can suppresses all warning messages or specific warning messages.

Example:

To suppress all warnings:

To suppress warnings 113 and 114:

Related information

Linker option --warnings-as-errors (Treat warnings as error)

--warnings-as-errors

EDE

1. From the Project menu, select Project Options...

2. Expand the Linker entry and select Warnings.

3. Enable the option Treat warnings as errors.

Command line syntax

Description

With this option you tell the linker to treat warnings as errors.

When the linker detects an error, it tries to continue the link process and reports other errors and warnings. However, the linker will exit with an exit status not equal zero (!= 0) and will not produce any output files.

Example

When a warning occurs, the linker considers it as an error.

Related information

Linker option -w (Suppress some or all warnings)


Copyright © 2003 Altium BV