Table of Contents

Name

multilink - Palm multi segment linker, version 0.3.

Synopsis

multilink [option|filename]...

Description

Multilink is a command line tool that can create multiple code segment applications and shared library files for the Palm Computing Platform. Multilink takes as input object files or libraries generated using gcc for PalmOS, as output multilink generates resource files corresponding to the application or shared library code, data, and relocation segments. As such multilink replaces the normal gcc-as-linker and obj-res steps in the build process. In addition, multilink generates the linker output files for each segment (the .out files), these files are required for debugging with gdb and may be used with binutils tools like nm.

NOTE: The multilink command you use probably comes in the form of the m68k-palmos-coff-multilink command (for use with the older prc-tools 0.5 tool chain), or m68k-palmos-multilink command (for use with the newer prc-tools 2.0 tool chain). For simplicity, this man page uses the simplified multilink name to refer to both forms of the command.

Options

The filename arguments may be any combination of object file or archive file names, or archive files specified using the -Ldir, -lname syntax. In addition -stdlib specifies that the standard libraries ( -lc and -lgcc ) should be included.

The option arguments may be intermixed with filename arguments, but in some cases, option arguments only effect the filename arguments that follow. The following describes the options that normally will be used:

-basename name
Specify the basename for output files. The basename is used in generating the output coff files (basenameNNNN.out) needed for debugging and the output grc files (TYPEXXXX.basename.grc) used to build your prc database.
-fid fid
FtrID jmptables will be installed using this ID. Without getting into too much detail, multilink stores it's inter-segment jump tables using a call to FtrSet(). This option specifies the creator ID passed as the first argument to this call. Normally this option should match the create ID of your application, and normally you should specify this option.
-gdb-script filename
Generate script with useful gdb commands. Out of the box, gdb does not know how to debug applications created using multilink. This option will generate a script with a useful 'load-segments' command tailored to your application.
-g
use debug versions of startup files.
-help
Print the standard usage information.
-segmentmap file
Explicitly define segments. Normally multilink automatically allocates objects to segments using a simple keep adding until the segment is full algorithm. Using a segmentmap file you may explicitly specify segments and which objects should go in each. The syntax of the segmentmap file is simple: objects are specified one per line, and a new segment is specified using the '<segment>' keyword. If the end of the segmentmap file is encountered before all objects have been specified, remaining objects will allocated according to the automatic algorithm.
-lname
Use the library named name when linking. Multilink searches a standard list of directories for the library, which is actually a file named 'libname.a'. The linker then uses this file as if it had been specified precisely by name. The directories searched include several standard system directories plus any that you specify with -L.
-Ldir
Add directory dir to the list of directories to be searched for -l.
-segmentsize n[k
Define maximum segment size (default is 30k). This option defines the maximum size of each segment. The theoretical maximum is currently 32k (16 bit relative addressing), but a fudge factor is usually needed. When using the a4-globals based tool chain (m68-palmos-coff-gcc) a smaller segment size is recommended as the fudge factor needs to be big enough to include the larger runtime support (27k seems to work well). If your links are failing with obscure error messages about the size of a branch, try a smaller segment size. Sorry, this is a bit lame.
-stdlib
link standard libs (-lc and -lgcc) into target.
-nostdlib
do not link standard libs into target
-syslib
Tell multilink target will be a System Library (default is target will be an app). This options changes the startup files that are linked into the target, changes the expected entry point from PilotMain to ShlibMain, and changes the resource type of that code segment from code0001 to libr0000.
-verbose
Be more verbose. There are multiple levels of verbosity.
-version
Print the version number.

The following options are somewhat esoteric and are not normally needed:

-debug
Output random debugging noise. This is mainly used for debugging multilink, but may be useful in overcoming sleeplessness.
-leavetmp
Leave generated glue files around. In the normal process of building your program, multilink generates a number of temporary assembler, and object files. Normally these are removed after use. This option disables the normal cleanup.
-libdir dir
Directory to look for startup files. The multilink command uses a number of Palm code files to handle things at runtime. This option specifies where to find those files. Normally, the default location is correct and this option is not needed.
-stdlib path
Path to look for standard library files (libgcc.a and libc.a). Path is a colon separated list of directories that multilink will look for the standard libraries (if they are being used). Normally, the default path is correct and this option is not needed.
-unused
Dump unused symbols. Useful in finding code that could be left out of your application.
-use-compiler compiler
Specify compiler to use. Multilink calls this command to compile assembler (.s) files and to link object (.o) files. Normally, the default path is correct and this option is not needed. Path is a colon separated list of directories that multilink will look for the standard libraries (if they are being used). Normally, the default path is correct and this option is not needed.
-a4-globals
Generate runtime code using a4-rel globals. Stay away.
-a5-globals
Generate runtime code using a5-rel globals. Stay away.
-relocation-old
Assume gcc 2.7 relocation information. Stay away.
-relocation-new
Assume gcc 2.95 relocation information. Stay away.

Environment Variables

MULTILINK_LIBDIR
If specified, this variable specifies the directory multilink will look for the Palm runtime files, just like the -libdir option. The -libdir option overrides this variable.
MULTILINK_STDLIBPATH
If specified, this variable specifies the path multilink will look for the standard library files (libc.a and libgcc.a), just like the -stdlibpath option. The -stdlibpath option overrides this variable.

Examples

The following example links all the objects in the current directory into a target application:

multilink -basename myapp -fid MYAP -g -stdlib *.o

The application code has access to the standard libraries (-stdlib), is debuggable using gdb (-g), will have a creator ID of 'MYAP' (-fid) and the multilink output files will use 'myapp' in their name.

The following example demonstrates links object in the current directory with some libraries:

multilink ... *.o libmath.a -L../ui -lui -lgcc

The following example shows how the -gdb-script option could be used:

$ m68k-palmos-multilink ... -gdb-script script.gdb *.o
$ par | build-prc | some tool for building the prc
$ m68k-palmos-gdb myapp0000.out
(gdb) source script.gdb
(gdb) target pilot localhost:2000
(gdb) load-segments

The following example shows how multilink could be used with pilrc and par:

rm -f *.bin *.grc
pilrc resources.rcp
m68k-palmos-multilink -fid MYAP *.o
par r myapp.prc MyApp appl MYAP *.bin *.grc

The following example shows how multilink could be used with pilrc and build-prc:

rm -f *.bin *.grc
pilrc resources.rcp
m68k-palmos-multilink -fid MYAP *.o
build-prc myapp.prc MyApp MYAP *.bin *.grc

Author

multilink was written by David Williams, djw@djw.org.


Table of Contents