Copyright (c) Hyperion Entertainment and contributors.
Difference between revisions of "SDK Developer Tools"
Line 572: | Line 572: | ||
== ARexx Interface == |
== ARexx Interface == |
||
+ | |||
+ | DistCCD has no ARexx interface. |
||
= DistCCMon-Amiga = |
= DistCCMon-Amiga = |
Revision as of 08:13, 17 June 2020
Contents
- 1 Introduction
- 2 AutoDoc
- 3 BuildLanguageCT
- 4 BuildMapTable
- 5 BumpRev
- 6 CatComp
- 7 ChangeRegs
- 8 DistCC
- 9 DistCCD
- 10 DistCCMon-Amiga
- 11 DistCCMon-Text
- 12 Expunge
- 13 FDTrans
- 14 FSTest
- 15 FSVPTool
- 16 GDB
- 17 GMake
- 18 GUnZip
- 19 GZip
- 20 IDLTool
- 21 ListDynDep
- 22 Localize
- 23 Make
- 24 MakeAudioMode
- 25 ModList
- 26 SH
- 27 TAR
- 28 USBSnoop
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:
- Update the revision number whenever the software is rebuilt
- 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:
| ||||||||||||
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.
| ||||||||||||
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)
Shell Usage
- Format
- Template
- [--help] [--version] [-P=--pid-file <file>] [-N=--nice <level>] [--user <user>] [-j=--jobs <limit>] [--job-lifetime <seconds>]
- [-p=--port <port>] [--listen <address>] [-a=--allow <ip/bits>] [--stats] [--stats-port <port>]
- [--log-level <level>] [--verbose] [--no-detach] [--log-file <file>] [--log-stderr] [--wizard]
- [--inetd] [--daemon]
- Location
- SDK:C
The options are:
Type | Option | Description |
---|---|---|
General | --help | Explain usage and exit. |
General | --version | Show version and exit. |
General | -P <file> or --pid-file <file> |
. |
General | -N <level> or --nice <level> |
. |
General | --user <user> | . |
General | -j <limit> or --jobs <limit> |
Maximum number of task to create. |
General | --job-lifetime <seconds> | Maximum lifetime of a compile request in seconds. |
Networking | -p <port> or --port <port> |
Listen on TCP port <port>. |
Networking | --listen <address> | Listen on TCP IP address <address>. |
Networking | -a <ip/bits> or --allow <ip/bits> |
. |
Networking | --stats | Enable statistics reporting via HTTP server. |
Networking | --stats-port <port> | Listen on TCP port for statistic requests. |
Debugging | --log-level <level> | . |
Debugging | --verbose | . |
Debugging | --no-detach | . |
Debugging | --log-file <file> | . |
Debugging | --log-stderr | Send messages to the stderr stream. |
Debugging | --wizard | . |
Operation Mode | --inetd | Serve client connected to stdin stream. Note: this option has been disabled. |
Operation Mode | --daemon | . |
ARexx Interface
DistCCD has no ARexx interface.
DistCCMon-Amiga
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
DistCCMon-Text
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
Expunge
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
FDTrans
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
FSTest
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
FSVPTool
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
GDB
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
GMake
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
GUnZip
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
GZip
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
IDLTool
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
ListDynDep
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
Localize
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
Make
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
MakeAudioMode
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
ModList
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
SH
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
TAR
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C
ARexx Interface
USBSnoop
Missing description.
Tool Types
Shell Usage
- Format
- Template
- Location
- SDK:C