| ld-tigcc Command-Line Options

| Invoking ld-tigcc and ar-tigcc | Next

In `ld-tigcc`, options and input files may appear in any order in the command line. Input files may be either object or archive (static library) files. They are handled differently depending on the type of the file: Object files are read completely in the order they are supplied; archive file members are read only if the program references a symbol they export. If multiple archive files export the same symbol, `ld-tigcc` uses the archive that is supplied first.
Output file names and variable names are usually set according to the name of the first object file in the command line, but they may be changed using the '--output' and '--varname' options described below. The file extensions depend on the exact output format used; they are usually what the transferring software expects them to be.
`ld-tigcc` recognizes the following options:

-h
--help
  Print a short description of all available options.
--version
  Print the version number of the tool and a short copyright notice.
-v
--verbose
  Print statistics about the linked program before terminating. These include the target calculators, program variable name and size, data variable size, BSS size (size of all uninitialized global variables), the total number of absolute relocs, the number of relocs which appear in the native format of the target OS, and optimization possibilities or results. In the IDE, these statistics are displayed automatically, unless this is turned off in the preferences or the program is run automatically after successful linking. If the linking process fails, no statistics are shown.
--dump
  Display all dumps of the program contents during the entire linking process. For details about dumps, see ld-tigcc Program Dumps.
--dumpn
  Display the n-th dump of the program contents. For details on the different linking stages and the associated dump numbers, see ld-tigcc Program Dumps.
--native
  Use TIGCC native mode by default. Without this option, the linker starts in kernel mode (for compatibility with existing programs), but this may be changed using special symbols (see Symbols to Control the Linker). For more information about modes, see TIGCC Linker Modes.
--fargo
  Use Fargo II mode and compile for the TI-92. This option is only available if Fargo support is compiled in. It exists for compatibility with existing Fargo II programs, which do not explicitly specify a mode and a target calculator.
--flash-os
  Use Flash OS mode. This mode creates an unsigned Flash operating system upgrade for the TI-89, TI-89 Titanium, TI-92+ and Voyage 200 calculators. This option is only available if Flash OS support is compiled in.
--remove-unused
  Remove unused sections. If a section is not referenced by another section, this option causes it to be removed. Startup sections are never removed; neither is the first section in Nostub mode. Note that in some cases, the linker cannot determine whether a section can be removed before merging it with another section; in this case, it is not removed even though it may not be referenced at all.
--optimize-relocs
  Update the destination symbol of relocation entries to the nearest available symbol, thereby making the offset as small as possible. This improves the readability of dumps and some diagnostic messages, but should not have any other effect than this.
--optimize-code
  Perform all code optimizations, including NOP, return, branch, move, test, and calculation optimization. Note that it is possible for code optimization to create invalid code or accidentally change data instead of code. The probability is not very high, so you should really enable code optimization at least partially, but if your program crashes for no apparent reason, try turning off code optimization. For more information about optimization, see TIGCC Linker Binary Code Fixup.
  --optimize-nops
    Perform NOP instruction removal.
  --optimize-returns
    Perform return sequence optimization.
  --optimize-branches
    Perform branch optimization.
  --optimize-moves
    Perform move/load/push optimization.
  --optimize-tests
    Perform compare/test optimization.
  --optimize-calcs
    Perform calculation optimization.
--cut-ranges
  Optimization has two effects: It can reduce the number of relocation entries, and it can make instructions smaller. Usually, the space gained from making the instructions smaller is filled with NOPs. If this option is used, the linker will attempt to cut out these ranges of code instead, making the size of the executable even smaller. This only works for input files that were assembled in all-relocs mode, but this is handled automatically if this option is used via the `tigcc` front-end or the TIGCC IDE.
--reorder-sections
  Reorder sections to make references shorter. The fixups (see above) can then fit those shorter references into smaller and faster addressing modes, so using this option can improve both size and speed. It can also allow the fixups to remove relocations or to turn F-Line jumps into faster branches. Since computing the optimal reordering is NP complete and very expensive in practical terms (the factorial of the number of sections is a huge factor), section reordering is implemented through heuristics. Therefore, the result is not guaranteed to be optimal. There are rare cases where section reordering can still take exponential time, these are due to hardcoded short references between sections rendering some reorderings impossible. In this case, the linker will emit warnings as impossible reorderings are encountered so you can follow the process, or stop it (and go fix your program, hardcoded short references between sections are not a good idea, that's what linker optimization is for!) if it takes too long. Startup sections can be reordered only with other startup sections with the same startup number. Non-startup sections can be reordered only with other non-startup sections. Sections which are emitted separately (e.g. a dynamically allocated BSS section or a data section in an external file) cannot be reordered at all.
--merge-constants
  Merge identical constants (including strings) to avoid duplication. Constant merging works on all symbols (actually, the ranges included within 2 symbols, where symbols at the same position are considered the same symbol) in sections marked mergeable. Constants can be merged if they are identical or if one of them is a prefix of the other. This can be used by the compiler to avoid duplicating string literals (and, if desired by the user, other constants) in multiple object files. Unaligned and aligned sections are distinguished to keep the linker from accidentally breaking the alignment while merging aligned constants with unaligned ones which happen to contain them as a prefix.
--omit-bss-init
  Skip the initialization of the BSS section, which holds uninitialized global variables. Older versions of TIGCC never initialized the BSS section, so many older programs do not rely on the initialization. If you use this option, you must be sure that there is really no code that relies on the initialization of global variables to zero (which means, among other things, that you have to use the compiler option '-fno-zero-initialized-in-bss'). For a safer alternative, try the __ld_omit_bss_init control symbol.
--outputbin
  Instead of creating a wrapped calculator variable that includes a folder and variable name, a checksum, and some extra information, write only the raw contents of the variable to the file. The file extension is changed in a way that allows different files to be generated for each target calculator but prevents confusion between raw and wrapped data.
-o file
--output file
  Write the output to the file named file.ext, where ext is the extension that fits the file type. file may include a path, but if it includes its own extension, ext will be appended anyway. This also sets the variable name to something that resembles file as closely as possible. Note that it does not do any error checking on the characters of the file parameter.
-n [folder\]name
--varname [folder\]name
  Include the folder name folder (`main` if unspecified) and variable name name in the wrapper file. If the file is not wrapped (i.e. if '--outputbin' has been specified), this option has no effect.
-d [folder\]name
--data-var [folder\]name
  Exclude all non-executable data (global variables) from the program and create an external variable for it. Note that you are absolutely required to make sure that no code is executed from the data section; otherwise it will crash depending on the calculator model: Newer calculators have a protection device that lets the operating system restrict the areas code can be executed from. name is the variable name to be assigned to the data variable. folder defines the folder of the variable; if it is not specified, the folder from the '--varname' option is used.
--data-var-copy=condition
  Defines when to create a copy of the data variable in RAM. If condition is `always`, the program will always work on a copy in RAM, which means that you may rely on the data being the same on every start of the program. However, if the data variable is not archived, you may easily run out of available memory. `archived` causes a copy to be created only if the data variable is archived; this is the default. If the variable is not archived, the program will work on the actual contents of the variable, so the values of all global variables will be kept even after the program finishes. `never` tells the linker to work on the original variable unconditionally, but since you may not write to the archive memory, you have to make sure that you never modify the value of a global variable. If the '--data-var' option is not specified as well, this option has no effect.