IAR Information Center for 8051

• The IAR universal linker
• Manual corrections and updates
• Important information
• Known problems in current version
• Program corrections and updates
• The XAR online manual

Important information

XAR 5.0.0.1 - 2010-May-17

• The version number now uses Major.Minor.Revision.Buildnumber.

XAR 4.61K - 2009-Feb-04

• The version of XAR is now tied to the version number of XLINK.

XAR 1.03A - 2002-03-18

• XAR, the IAR Universal Library Builder, is now included in the XLINK package. XAR has a very simple command line interface to construct library files from object files, which is likely to be far more convenient than using XLIB for the same purpose.

Known problems in current version

• There are currently no known problems.

Program corrections

XAR 5.0.0.2 - 2010-Jun-15

• The 5.0.0.1 XAR executable did not have version information.

XAR 4.61M - 2009-Apr-24

• The signon message was erroneous in XAR 4.61L.

XAR 1.03O - 2008-Mar-04

• XAR now handles protected UBROF files.

XAR 1.03L - 2005-04-15

• XAR terminated with an error when a UBROF file that was the result of the last module being deleted from a UBROF file by the XLIB Librarian was encountered.

XAR 1.03J - 2004-02-27

• Xar could terminate with an access violation while reading the extended command line file. This problem was introduced in XAR1.03I.

XAR 1.03I - 2004-02-17

• Better support for building libraries from the IAR Embedded Workbench.
• XAR terminated with an access violation if the length of a line in the extended command line file exceeded 65535 characters. If XAR encounters such a line now it terminates with error 15 (A file name in the file `file` exceeds the maximum file name length of number characters.).
• If the library building operation failed, XAR did not remove the incomplete library file.
• XAR now accepts white spaces and // comments in the extended command line file.

XAR 1.03H - 2003-10-06

• The sign on message of XAR did not display the options in alphabetical order

XAR 1.03G - 2003-04-11

• When XAR encountered a totally empty (0 bytes) file, the produced library file had an incorrect checksum.

XAR 1.03E - 2002-10-17

• XAR crashed when given just one argument, -V or -S.

XAR 1.03D - 2002-09-27

• XAR could crash when used with the -x option.

XAR 1.03C - 2002-07-10

• XAR can now read command files using the -x option. Everything in the command file will be interpreted as if it was entered on the command line. The main reason for this is that large libraries sometimes requires so many files that they become larger than the buffer allocated by the process XAR is run from. Note that this is a limitation in the OS/shell, not a limitation in XAR.
• XAR now warns when it encounters the same input file more than once. This is almost certainly an error but XAR will allow you to build the library anyway.

XAR 1.03B - 2002-05-30

• XAR now handles empty infiles, this was considered an error earlier.

XAR 1.03A - 2002-03-18

• This is the first public release of XAR so no problems are fixed.

XAR manual

Table of contents

[1.03A] Usage of XAR
[1.03I] XAR options
[1.03I] XAR extended command line file
[1.03C] Warning codes in XAR
[1.03I] Error codes in XAR


Usage of XAR

Building libraries with XAR is quite simple, just type either:
xar file1 file2 ... fileN -o lib
or
xar lib file1 file2 ... fileN
This will make XAR create a library called lib that consists of the files file1 to fileN.

XAR options

Aside from -o XAR has the following options:



-S Silent operation, nothing is printed if everything went well, this is the default setting for command line XAR.

-V Verbose, this prints the progress of XAR while it builds libraries, this is the default setting for the XAR used by the IAR Embedded Workbench.

-x filename, this extends the command line with the contents of the file 'filename'. See The Extended Command Line file for the details.

XAR Extended Command Line File

XAR can read command files using the -x option. The main reason for this is that large libraries sometimes requires so many files the command line becomes larger than the buffer allocated by the process XAR is run from. Note that this is a limitation in the OS/shell, not a limitation in XAR.

The command file may only contain file names, white spaces and comments, not options. All options must be specified on the command line.

• White spaces at the beginning of a line are ignored.
• All characters between an occurence of "//" and the next newline are ignored.
• All other characters are considered to be part of a file name. Once a non white space character has been encountered, the rest of the line will be considered a file name or a comment.

Warning codes in XAR

0 File 'filename' has already been added to the library

The file was added to the library before the processing of this file. This is almost certainly an error as all symbols in the file will be multiply defined.

Error codes in XAR

As simple as XAR is, sometimes something goes wrong. This is a list of the possible errors that XAR detects:

0 Not enough memory

XAR was unable to aquire the memory that it needed.

1 -o option requires an argument

XAR expects an argument after -o.

2 Unknown option 'option'

XAR encountered an unknown option on the command line.

3 Too few arguments

XAR expects to find more arguments

4 Same file as both input and output: 'filename'

One of the files is used as both input and output, as this would destroy an infile it is forbidden. If you really want to give the new library a name that is used by one of the infiles you will have to use a temporary file to build the library with XAR and rename that temporary file to the name you want afterwards.

5 Can't open library file 'filename' for writing

XAR was unable to open the library file for writing, the most probable explanation for this is that the library file is write protected.

6 Can't open object file 'filename'

XAR was unable to open the object file, the most probable explanation for this is that the file does not exist.

7 Error occured while writing to library file

An error ocurred while XAR was writing to the file.

8 'filename' is not a valid UBROF file

The file is not a valid UBROF file.

9 Error occured while reading from 'filename'

An error ocurred while XAR was reading the file.

10 Error occured while closing 'filename'

An error ocurred while XAR was closing the file.

11 XAR didn't find any bytes to read, is 'filename' empty ?

The object file seems to be empty. Note that this error only can occur in older versions of XAR.

12 'filename' didn't end as a valid UBROF file should

The file did not end as a UBROF file is supposed to end. Either the file is corrupt or the assembler / compiler produces corrupt output.

13 XAR can't fseek in library file

The call to fseek failed.

14 -x option requires an argument

You need to specify an argument for the -x option

15 A file name in the file `file` exceeds the maximum file name length of number characters.

A file name in the extended command line file is too long. The only recognized delimiter in the input file is newline, everything else is interpreted as a part of the file name.

Note: XAR does not distinguish between UBROF for different processors, as far as it is concerned a UBROF file is a UBROF file and if a user wants to build a library consisting of files from two different cpu:s it allows it.