Table of Contents
multilink - Palm multi segment linker, version 0.3.
multilink
[option|filename]...
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.
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.
- 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.
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
multilink was written by
David Williams, djw@djw.org.
Table of Contents