SDK Developer Tools

Introduction

The Software Development Kit (SDK) contains a suite of software tools to aid developers in making software for AmigaOS.

AutoDoc

AutoDoc extracts and sorts autodocs from the given files and prints them in the standard output.

Tool Types

(none)

Shell Usage

Format

AUTODOC [-t <number>] [-i] [-o] [-a] [-s] [-C] [-l <length>] [-w] [-c] [-f] [-r] [-F <file>] [-I] {<infile>}

Template

[-t number] [-i] [-o] [-a] [-s] [-C] [-l length] [-w] [-c] [-f] [-r] [-F file] [-I] {infile}

Location

SDK:C

The options are:

{<infile>}	List of files to be processed.
-t<number>	Turn tabulators to given number of spaces.
-i	Process only INTERNAL autodocs.
-o	Process only OBSOLETE autodocs.
-a	Do not process autodocs starting with an asterisk.
-s	Process autodocs starting with a semicolon.
-C	Process autodocs starting with "/*". This is the default setting.
-l<number>	Set the line length for the output. The default is 78.
-w	Turn off word wrapping.
-c	Do not convert "\*" to "/*" or "*\" to "*/".
-f	Do not add form feeds between the autodoc entries.
-r	Generate Troff source output.
-F<file>	Use <file> as a temporary file. The default temporary file is "tmpfile".
-I	Do not print "Table of Contents" before entries. If omitted, "Table of Contents" will be printed after the entries.

Example

Extract autodocs from files "main.c" and "functions.h" and redirect AutoDoc's output to file "MyDocs.doc".

1> autodoc -a -C main.c functions.h >MyDocs.doc

ARexx Interface

AutoDoc has no ARexx interface.

BuildLanguageCT

This tool generates a catalog translation file (CT file) from the current system language driver.

A new language.catalog can be created with a CatComp tool using the generated CT file and a language catalog descriptor file (located in "SYS:Locale-Source/language.cd").

Tool Types

(none)

Shell Usage

Format

BUILDLANGUAGECT

Template

(none)

Location

SDK:C

Example 1

List the current language driver strings.

 1> BuildLanguageCT

Example 2

Create a "language.ct" file with the built-in strings of the current system language driver.

 1> BuildLanguageCT >language.ct

ARexx Interface

BuildLanguageCT has no ARexx interface.

BuildMapTable

BuildMapTable converts Charset-To-Unicode mapping tables in text form (e.g. available at http://www.unicode.org/Public/MAPPINGS/) to mapping tables in binary form usable by diskfont.library.

BuildMapTable can either display a text form of the parsed table or create a binary mapping table in the "L:Charsets/" directory. Currently only 8-bit character set mapping tables are supported.

If "L:Charsets/character-sets" or "L:Charsets/custom-character-sets" contains a MIME name for an 8-bit character set where no mapping table in "L:Charsets/" does not exist, and you have a mapping table in text form, use BuildMapTable to create the binary mapping table and reboot (diskfont.library searches tables only once) to be able to use the new character set (e.g. in fonts or catalog files).

The expected format of text mapping tables is as follows:

• Anything from a '#' character to the end of a line is considered a comment.
• A valid line does contain the index on the left and the Unicode point at the right side, in either hexadecimal (starting with 0x or 0X) or octal (starting with 0) or decimal form, separated by empty space.

Example

0xA4 0x20AC # EURO SIGN

Tool Types

(none)

Shell Usage

Format

BUILDMAPTABLE <ASCII mapping table> [CHARSET]

Template

UNICODEMAPTABLE/A,CHARSET/K

Location

SDK:C

The parameters are:

UNICODEMAPTABLE	A character set mapping table file.
CHARSET	A MIME character set name or alias.

The UNICODEMAPTABLE parameter specifies a character set mapping table file to be read and the CHARSET parameter the binary mapping table file to be written.

The MIME character set name obtained from diskfont.library will be used as file name of the binary character set mapping table which will be stored in "L:Charsets/". If the CHARSET parameter is omitted, no file will be written, instead the resulting mapping table is displayed in text form.

Example 1

Parse a text file "CP1258.TXT" and display a list of entries with the index on the left and the Unicode codepoint at the right side.

 1> BuildMapTable CP1258.TXT

Note: unmapped entries (with Unicode codepoint 0) are not displayed.

Example 2

Parse a text file "8859-1.TXT" and create a file "L:Charsets/ISO-8859-1" (latin1 is an alias for ISO-8859-1).

 1> BuildMapTable 8859-1.TXT CHARSET LATIN1

ARexx Interface

BuildMapTable has no ARexx interface.

BumpRev

BumpRev updates version and revision information and makes this available for program code to use it. It generates header file for C and Assembly language programs to use. The typical application is to "bump" (i.e. increment) the revision number of a program, library, device, etc. after it has been changed and before it is released.

There are two common practices to use BumpRev:

1. Update the revision number whenever the software is rebuilt
2. Update the revision number only when a new release is created

The advantage of a. is that you can integrate it into your built process, and you won't ever forget to bump a revision number when something has changed. The disadvantage is that revision numbers can increase very quickly (do not worry: you have 65535 revisions to spare).

The advantage of b. is that it saves revision numbers (which can become scarce), but the disadvantage is that you might forget to bump a revision number before you rebuilt a new release.

Practice a. has a lot going for it, and it was the preferred default at Commodore when AmigaOS 2.x/3.x were created.

Tool Types

(none)

Shell Usage

Format

BUMPREV [-q] [-v <version>] [-r <revision>] [-n <name>] [-b <base name>] [-d <depend list file>]

[-e <exclude suffix>] [-i <include suffix>] [-D] [-L] [<version> <base name> [<depend list file>]]

Template

[-q] [-v <version>] [-r <revision>] [-n <name>] [-b <base name>] [-d <depend list file>]

[-e <exclude suffix>] [-i <include suffix>] [-D] [-L] [<version> <base name> [<depend list file>]]

Location

SDK:C

The options are:

-q	Activate "quiet" operation, i.e. will not print any warning or progress messages, but will print error message.
-v <version>	Set the version number to use. This must be a number greater than 0. Note that version numbers greater than 255 are unsafe to use for some applications since a "struct Resident" only reserves an unsigned 8-bit integer for storing a version number in it.
-r <revision>	Set the revision number to use rather than let BumpRev read and increment it instead. This must be a number greater than 0.
-n <name>	Set the name of the program, library, device, etc. If it is not the same as the base name (see below). This can be useful for software built on systems which do not use a case-insensitive file system
-b <base name>	Set the base file name all the work and header file names are generated from. This also becomes the name that is written to the files unless you override this with the -n option (see above).
-d <depend list file>	A file which contains a list of file names whose modification times should be compared against the modification time of the file which contains the revision number. If any of these files has been modified after the revision number file has a new revision will be created; otherwise BumpRev will exit immediately. There must be one file name per line. Note that if you give "-" as the file name, BumpRev will try to read the file name list from standard input.
-e <exclude suffix>	By default BumpRev generates three header files: one for use with C and two for use with Assembly. language The C header file name ends with ".h" and the two Assembly language file names end with ".i" and ".s", respectively. You can tell BumpRev not to create all of these files with the -e option.
-i <include suffix>	This controls which header files should be created, with the default being the ".h", ".i", and ".s" files. The difference between the -i option and -e option is that with -i you say exactly what header files you want, and not what you do not want.
-D	Add a DEVNAME definition to the output files.
-L	Add a LIBNAME definition to the output files.

You can specify the base name, the version number and the dependencies file name both using options and as regular parameters. But you do not need to specify both. For example, the following commands are equivalent:

  BumpRev -b foo 1
  BumpRev 1 foo
  BumpRev -v 1 foo
  BumpRev -v 1 -b foo

The following commands are equivalent, too:

  BumpRev 1 bar dependencies_file
  BumpRev -b bar 1 dependencies_file
  BumpRev -v 1 -d dependencies_file bar
  BumpRev -v 1 -b bar dependencies_file

Example 1

Create or update a revision file "foo_rev.rev" unless it already exists, and create three more header files: "foo_rev.h", "foo_rev.1", and "foo_rev.s".

  1> BumpRev 1 foo
  BumpRev: Creating new file "foo_rev.rev"
  BumpRev: Bumped "foo" to version 1.1.

If you invoke BumpRev with the same parameters again, the revision file will be updated, incrementing the revision number. The three header files will be updated, too.

  1> BumpRev 1 foo
  BumpRev: Bumped "foo" to version 1.2.

Example 2

The name you give BumpRev goes into the names of the header files, and it also becomes the name printed in each string. This can be overridden with the -n option.

  1> BumpRev -n Bar 1 bar
  BumpRev: Creating new file "bar_rev.rev".
  BumpRev: Bumped "Bar" to version 1.1.

The resulting files still use the same base name, but the names printed in the files are different.

bar_rev.h

#define VERSION  1
#define REVISION 1
#define DATE     "15.6.2020"
#define VERS     "Bar 1.1"
#define VSTRING  "Bar 1.1 (15.6.2020)\r\n"
#define VERSTAG  "\0$VER: Bar 1.1 (15.6.2020)"

Example 3

BumpRev defaults to create three header files, but at times there may be only one you need. To create just the C language header file, you would use the -e option like this:

  1> BumpRev -e si 1 baz

This would create only "baz_rev.h" and omit "baz_rev.i" and "baz_rev.s".

ARexx Interface

BumpRev has no ARexx interface.

CatComp

CatComp is a program to handle the creation and maintenance of the message catalogs used by locale.library. Message catalogs are IFF files read by locale.library that contain all the text strings used by an application. By providing several of these catalog files, an application can use locale.library and transparently adapt itself to the user's preferred language.

CatComp reads and processes two kinds of input files, and produces five types of output files.

CatComp Input Files

The first kind of file read by CatComp is a catalog description file. That file describes all the strings used by an application. There is one such file per localized application. In this file, you assign numbers to all the application strings as well as specify their minimum and maximum lengths.

The second kind of file read by CatComp is a catalog translation file. That file contains all strings from the application translated to one language. There is one catalog translation file per language supported by a localized application.

CatComp Output Files

CatComp can produce several different kinds of output files. The first is an IFF catalog. These are regular IFF files. There is one catalog produced for every catalog text file successfully processed. Catalogs are read directly by locale.library whenever the OpenCatalog() call is made.

The second type of file output by CatComp is an empty translation file. This is useful when starting a translation. It lets CatComp convert a catalog description file into a ready to fill-in translation file.

The third type of file output by CatComp is a new translation file based on an old one. This is useful when re-starting a translation after a catalog description file was modified, because the new and the modified strings will be stored in the the new catalog translation file.

The fourth and fifth type of files output by CatComp are C and Assembly language programming source files. These are used by application writers to convert catalog description files into source files that can be directly used in their applications.

The sixth and seventh type of files output by CatComp are Modula-2 language definition and implementation source files, which are used by programmers in much the same way C and Assembly files are used.

Finally, the last type of file output by CatComp is an AmigaDOS load file. These load files are used by application writers to include a set of strings directly inside an application. This is normally used to encode the default strings that an application uses when there are no external catalogs available.

File Formats

To learn more about CatComp's input and output files, consult CatComp documentation located in the Software Development Kit: SDK:Documentation/Tools/Locale/CatComp.doc.

Tool Types

(none)

Shell Usage

Format

CATCOMP <descriptor> [<cd file>] [CATALOG=<catalog file>] [CTFILE=<ct file>] [CFILE=<c source file>]

[SYMBOLS={<symbol>}] [VERBOSITY=<verbosity level>] [NOOPTIM] [NONUMBERS] [NOSTRINGS] [NOARRAY]

[NOBLOCK] [NOCODE] [SORT] [COMMENTS]

Template

DESCRIPTOR/A,TRANSLATION,CATALOG/K,CTFILE/K,CFILE/K,SYMBOLS/M/K,VB=VERBOSITY/N/K,NOOPTIM/S,

NONUMBERS/S,NOSTRINGS/S,NOARRAY/S,NOBLOCK/S,NOCODE/S,SORT/S,COMMENTS/S

Location

SDK:C

The options are:

DESCRIPTOR	Specifies the name of a catalog descriptor file. Typically, the file extension for catalog descriptor files is ".cd".
TRANSLATION	Specifies the name of a catalog translation file. Typically, the file extension for catalog translation files is ".ct".
CATALOG	Specifies the name of the IFF catalog file to produce. When this option is specified, a translation file must have been given in the previous argument.
CTFILE	Specifies the name of the catalog translation file to produce. This option only requires a catalog descriptor file be provided, then the catalog translation file will be blank. When you also specified a source translation file, the version string, language, codeset, and strings of the source translation file will be copied to the new translation file.
CFILE	Specifies the name of the C language source file header to produce. This option only requires a catalog descriptor file be provided, there is no need for a translation file.
SYMBOLS	Specifies any number of symbols that are used for determining which section of the available strings get included within generated C, Assembly, and object files. The valid symbols are: Symbol Description CATCOMP_NUMBERS This symbol causes the name of each string to be defined with the value of its ID, as listed in the catalog descriptor file. CATCOMP_STRINGS This symbol causes each string to be defined. CATCOMP_ARRAY This symbol causes a table of CatCompArray structure to become available. CATCOMP_BLOCK This symbol causes a compact table of all strings and their ID values to be generated. CATCOMP_CODE This symbol causes the generation of source code for a function called GetString().
VB or VERBOSITY	Specifies the amount of information CatComp should output while doing some processing. The lower this number, the less CatComp will output messages. Verbosity Level Description 0 No warnings 1 At verbosity level 1 or higher, warnings about C language formatting commands and warnings about missing strings in catalog translation files can appear. 2 At verbosity level 2 or higher, warnings about missing trailing ellipsis (...) in catalog descriptor files can appear. 3 At verbosity level 3 or higher, warnings about trailing blank characters and non-ASCII characters in catalog descriptor files can appear. This is the default verbosity level. 4 At verbosity level 4 or higher, CatComp will output every message it could. This includes warnings about identical strings in catalog descriptor and catalog translation files (which are not shown when the NOOPTIM switch was spesified).
NOOPTIM	When generating a catalog file, CatComp normally skips strings that are identical in the catalog descriptor file and in the catalog translation file and does not include them in the generated catalog file. This option disables this optimization.
NONUMBERS	This option is only useful when generate C or Assembly language header files. It prevents the generation of the CATCOMP_NUMBERS section within the header file.
NOSTRINGS	This option is only useful when generate C or Assembly language header files. It prevents the generation of the CATCOMP_STRINGS section within the header file.
NOARRAY	This option is only useful when generate C or Assembly language header files. It prevents the generation of the CATCOMP_ARRAY section within the header file.
NOBLOCK	This option is only useful when generate C or Assembly language header files. It prevents the generation of the CATCOMP_BLOCK section within the header file.
NOCODE	This option is only useful when generate C or Assembly language header files. It prevents the generation of the CATCOMP_CODE section within the header file.
SORT	When specified, all strings will be sorted by ID before they are written to header/assembler/object/catalog files. Catalog translation files will, however, get written in the same order in which the strings showed up in the catalog descriptor file.
COMMENTS	When both this switch and CTFILE were spesified, the comment lines from the catalog description file will be copied into the new catalog translation file.

Example 1

Test if "app.cd" is a valid catalog descriptor file.

  1> CatComp app.cd

Example 2

Generate a blank translation file called "app.ct".

  1> CatComp app.cd CTFILE app.ct

Example 3

Create a catalog file "app.catalog".

  1> CatComp app.cd app.ct CATALOG app.catalog

ARexx Interface

CatComp has no ARexx interface.

ChangeRegs

Missing description.

Tool Types

(none)

Shell Usage

Format

CHANGEREGS <source file> <destination> [HEADER] [NEWSUFFIX=<file extension>]

Template

SRC=SOURCE/A,DEST=DESTPATH,HEADER/S,NS=NEWSUFFIX/K

Location

SDK:C

The parameters are:

SRC or SOURCE	C source code file to be processed.
DEST or DESTPATH	Path to directory where the processed source code will be saved.
HEADER	Add register definitions for SAS/C and GNU/C at the beginning of the source code.
NS or NEWSUFFIX	Save the processed source code with a new file extension.

ARexx Interface

ChangeRegs has no ARexx interface.

DistCC

DistCC is a program to distribute builds of C or C++ code across several machines on a network. It does not require all machines to share a filesystem, have synchronized clocks, or to have the same libraries or header files installed. They can even have different processors or operating systems if cross-compilers are installed.

DistCC is not itself a compiler, but rather a front-end to the GNU C/C++ compiler (gcc), or another compiler of your choice. All the regular gcc options and features work as normal.

For each job, DistCC sends the complete preprocessed source code and compiler arguments across the network from the client to a compilation server. Compilation is driven by a client machine, which is typically the developer's workstation. The DistCC client runs on this machine, as does Make, the preprocessor, the linker, and other stages of the build process. Any number of volunteer machines act as compilation servers and help the client to build the program by running the DistCCD daemon, C compiler and assembler as required.

DistCC runs across TCP sockets (on port 3632 by default). For TCP connections the volunteers must run the DistCCD daemon directly.

DistCC is intended to be used with GNU Make's -j option, which runs several compiler processes concurrently. DistCC spreads the jobs across both local and remote CPUs. Because DistCC is able to distribute most of the work across the network, a higher concurrency level can be used than for local builds. As a rule of thumb, the -j value should be set to about twice the total number of available server CPUs but subject to client limitations. This setting allows for maximal interleaving of tasks being blocked waiting for disk or network IO.

It is strongly recommended that you install the same compiler version on all machines participating in a build. Incompatible compilers may cause mysterious compile or link failures.

Environment Variables

DistCC uses the following environment variables:

Variable	Description
DISTCC_DIR	Path to the host list and locks files.
DISTCC_HOSTS	Name of the host list file. The default name is "hosts".
DISTCC_LOG	Name of the log file. When set, DistCC writes its output to the log.
DISTCC_VERBOSE	Setting this to 1 enables debug messages.

Server Specification

A list of servers will be taken from a file pointed by an environment variable $DISTCC_HOSTS or $DISTCC_DIR/hosts. In the file each host can be given in any of these forms:

Host Address / Command	Description
localhost	Run in place.
<host>	TCP connection to a specified host's port 3632.
<host>:<port>	TCP connection to a specified host's port number <port>.
--randomize	Randomize the server list before execution.

Tool Types

(none)

Shell Usage

Format

DISTCC [--help] [--version] [--show-hosts] [-j] [<compiler>] [<compiler options>]

Template

[--help] [--version] [--show-hosts] [-j] [<compiler>] [<compiler options>]

Location

SDK:C

The options are:

--help	Explain DistCC usage and exit.
--version	Show DistCC version and exit.
--show-hosts	Show host list and exit.
-j	Calculate the concurrency level from the host list.
<compiler>	Compiler to use. Defaults to cc.
<compiler options>	Compiler options. As a minimum, you should supply a list of source files to be compiled.

ARexx Interface

DistCC has no ARexx interface.

DistCCD

Missing description.

Tool Types

(none)

DistCCMon-Amiga

Missing description.

Shell Usage

Format

Template

Location

SDK:C

DistCCMon-Text

Missing description.

Shell Usage

Format

Template

Location

SDK:C

Expunge

Missing description.

Shell Usage

Format

Template

Location

SDK:C

FDTrans

Missing description.

Shell Usage

Format

Template

Location

SDK:C

FSTest

Missing description.

Shell Usage

Format

Template

Location

SDK:C

FSVPTool

Missing description.

Shell Usage

Format

Template

Location

SDK:C

GDB

Missing description.

Shell Usage

Format

Template

Location

SDK:C

GMake

Missing description.

Shell Usage

Format

Template

Location

SDK:C

GUnZip

Missing description.

Shell Usage

Format

Template

Location

SDK:C

GZip

Missing description.

Shell Usage

Format

Template

Location

SDK:C

IDLTool

Missing description.

Shell Usage

Format

Template

Location

SDK:C

ListDynDep

Missing description.

Shell Usage

Format

Template

Location

SDK:C

Localize

Missing description.

Shell Usage

Format

Template

Location

SDK:C

Make

Missing description.

Shell Usage

Format

Template

Location

SDK:C

MakeAudioMode

Missing description.

Shell Usage

Format

Template

Location

SDK:C

ModList

Missing description.

Shell Usage

Format

Template

Location

SDK:C

SH

Missing description.

Shell Usage

Format

Template

Location

SDK:C

TAR

Missing description.

Shell Usage

Format

Template

Location

SDK:C

USBSnoop

Missing description.

Shell Usage

Format

Template

Location

SDK:C