============================================================================== README (emx.txt) 2003-05-08 ============================================================================== Here are a couple of preliminary notes about the programs and libraries shipped in the epocemx kit. Most of the stuff is licensed under the GNU General Public License (GPL, see COPYING); however, libemx.a isn't (see COPYING.EMX), so linking with libemx.a doesn't infect your programs with the GPL. The best way to run the command line programs under EPOC is to run them from sh.exe using EmxConsole. To get started, run \emx.exe. epocemx is available for ER5 only. ------------------------------------------------------------------------------ Important note ------------------------------------------------------------------------------ This release of emx.dll is not compatible with executables built for earlier versions of emx.dll (up to and including epocemx-20020523, ie, versions less than 1.0). Incompatible executables will be terminated by panic EMX 11. Rebuilding those executables solves that problem. ------------------------------------------------------------------------------ SIS files ------------------------------------------------------------------------------ If you don't want to develop programs on your EPOC device, the following SIS files should be sufficient: emxbzip2.sis bzip2, bzip2recover ([un]compressing files) emxdiff.sis GNU diff (comparing files) emxfind.sis GNU find and xargs (searching for files) emxgawk.sis GNU awk (pattern scanning and text processing) emxgrep.sis GNU grep (searching files) emxgzip.sis GNU gzip, gunzip, zcat ([un]compressing files) emxless.sis less (the opposite of more, a pager) emxrecode.sis GNU recode (convert files between character sets) emxsed.sis GNU sed (stream editor) emxshutils.sis GNU shell utilities emxtar.sis GNU tar (archiver) emxtextutils.sis GNU text utilities emxunzip.sis a port of unzip emxuser.sis contains the following three components: emxdll.sis emx.dll and emxrun.exe -- essential emxconsole.sis EmxConsole -- essential for command line programs emxshell.sis highly recommended for command line programs emxzip.sis a port of zip At least, emxuser.sis must be installed. For developing programs on your EPOC device, you also have to install these SIS files (development system): emxbinutils.sis GNU binary utilities emxdev.sis epocemx development tools emxgcc-base.sis GCC base package (driver and preprocessor) emxgcc-c.sis GCC C compiler emxgcc-c++.sis GCC C++ compiler and parts of the ER5 C++ SDK (you need header files and import libraries from CPPER5six.zip and CPPER5seven.zip). Note that emxrsc.exe (of emxdev.sis) requires cpp.exe (which lives in emxgcc-base.sis). ------------------------------------------------------------------------------ Installing the SIS files ------------------------------------------------------------------------------ Select the desired SIS files from the lists above and install them. If you don't know how to install software from SIS files, epocemx currently isn't for you. If epocemx is required by third-party software, see the documentation of that software. For performance reasons, it's recommended to install the files of emxuser.sis on drive C:. You can install epocemx (and the ported programs) either on one drive or on two drives. If you want to use three or more drives, you have to figure out yourself what to do. The recommended setup is to install the files of emxuser.sis on drive C:, the development system on drive D: (if installed at all), and the other packages either on drive C: or drive D:. In that case, no additional work is required. If you install everything on drive C:, go to the root directory of drive C:, start emx.exe, and type: cd / rm usr ln -s c:/emx usr If you install everything on drive D:, no additional work is required. If you install everything on drive E:, go to directory \emx\bin of drive E:, start sh.exe, and type: cd / rm usr ln -s e:/emx usr If you install the files of emxuser.sis on drive C:, the development system on drive E: (if installed at all), and the other packages either on drive C: or drive E:, go to the root directory of drive C:, start emx.exe, and type: cd / rm usr ln -s e:/emx usr Other combinations of packages and drives are left as exercise. Background: The pathname "/usr" is used for the "\emx" directory of the secondary installation drive (if present). The pathname "/usr" is hardcoded into many programs of the development system, therefore "/usr" must point to "\emx" on the drive on which the development system is installed. See below for details. ------------------------------------------------------------------------------ EPOC directories and Unix directories ------------------------------------------------------------------------------ The following EPOC directories will be used: EPOC Unix Description -------------------------------------------------------------------- \ emx.exe \System\Apps\EmxConsole The EmxConsole application \System\Apps\EmxDevice The EmxDevice application \System\Apps\EmxLink The EmxLink application \System\Libs emx.dll, emxrun.exe, and other DLLs \System\Data emx.ini \emx / Unix root direcory (see below) \emx\bin /bin, /usr/bin User-visible programs and some DLLs \emx\doc /doc, /usr/doc Documentation \emx\epocsdk /usr/epocsdk Files from the ER5 C++ SDK: \emx\home /home .profile \emx\include /usr/include GNU and emx header files \emx\lib /usr/lib emx libraries \emx\lib\gcc-lib /usr/lib/gcc-lib GNU libraries/programs for GCC \emx\man /man, /usr/man Manual pages (read with `less') The Unix root directory ("/") is mapped to EPOC directory \emx on the drive where emx.dll is installed. Under that directory, there are symbolic links "c", "d", "e", and "z", pointing to EPOC directories "c:\", "d:\", "e:\", and "z:\", respectively. Example: Assuming that emx.dll is installed on drive C:, "/d/system" is mapped to "c:\emx\d\system", which in turn is mapped to "d:\system". "/usr" (alias "\emx\usr" on the drive on which emx.dll is installed) is a symbolic link to the "second" installation drive. If everything is installed on one drive, "/usr" is equivalent to "/". The Unix directory "//" is mapped to the root directory of the current working directory's EPOC drive. In `sh', you'll note that "cd //" will change the current working directory to, say, "/C:/", which denotes the root directory of drive C:, as absolute Unix pathname. EPOC paths can also be used, either with "/" or "\" as separator (note that "\" must be escaped in the shell): cd c:/documents cd 'c:\documents' There are symbolic links /c -> c:\ /d -> d:\ /e -> e:\ /z -> z:\ therefore you can also do this: cd /c/documents Devices: /dev/console same as /dev/tty /dev/null /dev/raw/c raw access to disk C: (and so on) /dev/tty same as /dev/console /dev/zero ------------------------------------------------------------------------------ GCC: arm-epoc-pe-gcc / gcc.exe ------------------------------------------------------------------------------ Under Unix, the cross compiler is called "arm-epoc-pe-gcc", under EPOC, the compiler is called "gcc". You can build directly EPOC executables, without having to invoke ld, dlltool, or emximage yourself: arm-epoc-pe-gcc -o hello.exe hello.c Use -shared to create a DLL: arm-epoc-pe-gcc -shared -o sample.dll sample.cc GCC does this by calling eld instead of ld; eld calls the appropriate tools. See the eld documentation for details. It is unknown whether this port of GCC works with (those incredible) Makefiles generated by makmake of the ER5 C++ SDK. This port of GCC is based on the 20010205 snapshot, the last one which supported the old C++ ABI required by the EPOC API. New and changed GCC switches: -heap MAX Set the maximum heap size (reserved size) to MAX bytes. The number can be given as hexadecimal number by prepending "0x". You can give the number in KB by appending "K", in MB by appending "M". The default value of MAX is 1M. Example: -heap 8M -heap-min MIN Set the minimum heap size (committed size) to MIN bytes. The number can be given as hexadecimal number by prepending "0x". You can give the number in KB by appending "K", in MB by appending "M". The default value of MIN is 4K. -shared Build an EPOC DLL file (.DLL or .APP or whatever). -stack MAX Set the maximum stack size to MAX bytes. The stack size can be given as hexadecimal number by prepending "0x". You can give the stack size in KB by appending "K", in MB by appending "M". The default stack size is 64K. Example: -stack 128K -uid1 UID1 -uid2 UID2 -uid3 UID3 Set the UIDs of the executable file. The UIDs can be given as hexadecimal numbers by prepending "0x". The default for UID1 is 0x10000079 with -shared, 0x1000007a without -shared. With -shared, the default for UID2 is 0x1000006c if the output file name ends with ".app", 0x1000008d if the output file name ends with ".dll", 0x00000000 otherwise. Usually, only -uid3 is required. If you need the -u (linker) switch to fake a reference to a symbol, insert a space between -u and the symbol name. -Zdef DEFNAME Write a .def file named DEFNAME. Can be used with -shared only. Example: -Zdef sample.def -Zexportdata LISTNAME Export data from a DLL; LISTNAME is the name of a file containing the symbols to be exported, one symbol per line. Only variables in .data and .bss can be exported, const variables in .rdata cannot be exported. This switch can only be used with -Zimplib; moreover, the address of the data section must be set with -Tdata. -Zimplib LIBNAME Write an import library named LIBNAME. This switch can be used only with -shared. Example: -Zimplib mylib.lib -Zmap MAPNAME Write a map file named MAPNAME. Example: -Zmap sample.map -Znoemx Use the startup code of the ER5 C++ SDK, don't link with libemx.a Two additional file name suffixes are treated specially by GCC (and eld): .def Module definition file containing an EXPORTS statement defining the symbols to be exported and the ordinals to be used (unless overriden by a .frz file) .frz Module definition file (freeze file) containing an EXPORTS statement defining the ordinals to be used for exporting the symbols listed in the EXPORTS statement. The DLL may export additional symbols, which will be assigned ordinals not used by the freeze file. The ordinals defined in a freeze file override the ordinals defined in any .def file. Any number of .def or .frz files can be used, but all the definitions in .def must not conflict with each other, and the definitions in .frz files must not conflict with each other. Conflicts between definitions in .def files and .frz files are resolved in favor of the definitions in .frz files. If at least one .def file is used, only the symbols listed in the EXPORTS statements of the .def and .frz files will be exported. If no .def file is used, eld runs dlltool to find all the symbols to be exported (marked with EXPORT_C in the source code). If .frz files are used, the ordinals defined in those files will be used. Any (new) symbols found by dlltool which are not defined in .frz files will be assigned ordinals which are not used by the .frz files and warnings will be issued to tell you that there are new symbols and you should create a new freeze file when releasing the DLL. Use a .frz file if you want to maintain binary compatibility with a previous release of a DLL (as EPOC imports by ordinal, the ordinals must stay unchanged). Use the .def file of the previous version of the DLL as .frz file of the new DLL. That .def file can be generated with the -Zdef switch of GCC or with dlltool. Use a .def file if you want to control exports and ordinals completely yourself, that is, if not all symbols marked EXPORT_C should be exported. But note that .frz files may override your .def files. Use neither a .frz nor a .def file during development of a DLL or for the first release of a DLL. To link against a library ABC, use the switch -lABC. Example: -leikon You don't need -lestlib and -leuser as ESTLIB isn't needed and -leuser is provided by default unless the -nostdlib option is used. In fact, you must never use -lestlib as that would break emx.dll (unless you also use -Znoemx). To save memory under EPOC, you should create the directory /usr/tmp and let the TMPDIR environment variable point to that directory: mkdir /usr/tmp export TMPDIR=/usr/tmp Note that this will increase the power consumption and reduce the lifetime of the CF card. ------------------------------------------------------------------------------ Building AIF files: emxaif / emxaif.exe ------------------------------------------------------------------------------ emxaif builds an AIF file from an RSC or RSS file and a MBM file (icons). To build an AIF file, call emxaif like this: emxaif [-s] [-v] [-P] [-D SYMBOL[=VALUE]]... [-o FILENAME.aif] FILENAME.rsc [FILENAME.mbm] FILENAME.rsc is the resource file specifying the UID and other features of the application. If the filename ends with ".rss", emxaif will automatically run emxrsc to compile that resource file and will then use the compiled file. FILENAME.mbm must be specified if at least one icon is to be used. These switches are available: -o FILENAME.aif Write the AIF file FILENAME.aif; that file will be used on the EPOC device. If the -o switch is not used, emxaif will derive the name of the AIF file from the name of the source file FILENAME.rsc by replacing the suffix with ".aif". -s Force emxaif to run emxrsc even if the suffix of FILENAME is not ".rss". -v Verbose mode; list the contents of the RSC file and the MBM file. The contents of the RSC file will be listed in a format suitable as input of emxrsc. -D SYMBOL=[VALUE] This switch is passed down to emxrsc. emxrsc will pass it down to the C preprocessor. -P This switch is passed down to emxrsc. With -P, emxrsc won't run the C preprocessor. emxaif can also be used to list the contents of an AIF or MBM file: emxaif [p] -d FILENAME [-o OUTPUT] These switches are available: -p Dump pixels (only compression schemes 0 and 1 are supported) -d FILENAME Dump (list) the AIF or MBM file FILENAME. -o OUTPUT Write to the file OUTPUT instead of stdout There's not yet available a tool comparable to bmconv; you have to create the MBM file on your EPOC device or use bmconv on a Windows machine. ------------------------------------------------------------------------------ Dumping executables: emxdump / emxdump.exe ------------------------------------------------------------------------------ Dumps and checks an EPOC executable file. Usage: emxdump [SWITCHES] INPUTFILE [OUTPUTFILE] INPUTFILE is the executable file to disect; output goes to OUTPUTFILE. If no OUTPUTFILE is specified, emxdump will write to stdout (quite unusable under EPOC). These switches are available: -8 Assume that characters having codes 0x20 through 0xff are printable. Without -8, characters having codes 0x20 through 0x7e are considered to be printable. In the hex dumps, a dot is displayed instead of a non-printable character -d Disassemble the text section. The disassembler is far from complete, using it may violate licenses anyway -i Use the import list files $ROOT/epocsdk/lib/epoc.imp and $ROOT/lib/emx.imp, which list all symbols of the ER5 C++ SDK import libraries and libemx.a, respectively. Using import list files enables emxdump to print the names of exported and imported symbols in the dump of the import table and in the disassembly listing -I FILE Read an import list file from FILE. You can specifiy multiple files by using multiple -I switches An import list file is a text file which looks like this: DLL FOO[00000000].DLL 1 E32Dll__F10TDllReason 2 whatever A line starting with "DLL" defines the DLL to which the succeeding lines apply, up to the next DLL line. A line starting with a number lists the ordinal and the name of an import from that DLL. There can be any number of DLL lines in one file. emxdump keeps track of all the bytes read from the input file and checks whether each byte has been read exactly once. ------------------------------------------------------------------------------ Creating EPOC executables: emximage / emximage.exe ------------------------------------------------------------------------------ emximage (like the SDK's petran) transforms COFF/PE executable files into EPOC executable files. It also can dump COFF/PE executable files. This program is called by eld, which in turn is called by GCC, so you usually don't have to call emximage directly. There are three ways to call emximage: Transforming a COFF/PE executable file into an EPOC executable file: emximage [switches] INPUTFILE OUTPUTFILE Modifying (applying switch values) to an existing EPOC executable file: emximage [switches] FILE Dumping a COFF/PE executable file: emximage -d INPUTFILE The following switches are available: -d Dump file contents -D Enable output for debugging emximage -v Verbose -xpetran Output will be closer to XPeTran's -call[entrypoint] Call DLL entry point E32Dll (default) -nocall[entrypoint] Don't call DLL entry point E32Dll -moving Create relocatable EXE file (default) -fixed Create non-relocatable EXE file -flags FLAGS Set flags -acs Use alternative code checksum -allowdlldata Don't reject DLLs with data -exportdata LIST LIB Export data symbols, appending to LIB -Tdata ADDR Set data base address -stack SIZE Set stack size -heap MIN MAX Set heap size -priority PRIO Set process priority -uid1 UID1 Set UID1 -uid2 UID2 Set UID2 -uid3 UID3 Set UID3 If all three UIDs are zero (which is the default setting) when creating an EPOC executable, UID1 will be set to 0x1000007a (EXE). The -acs switch causes the code checksum to be replaced with its complement to work around a problem in EPOC. The -acs can be used only for programs which use the emx startup code, emxexe.o, as the checksum is also changed in the emx header (which is defined in emxexe.o), resulting in a checksum which is still correct. See spawn*() for details. If -Tdata is used with ADDR between 0x30000000 and 0x3ff00000, emximage won't check for DLLs with data. The -exportdata switch is used for exporting data from DLLs with data (that is, -Tdata must be used). LIST is the name of a file containing the symbols to be exported, one symbol per line; empty lines and lines starting with ";" are ignored. Only variables in .data and .bss can be exported, const variables in .rdata cannot be exported. Modules defining absolute symbols are appended to the library file LIB (which is created if it does not yet exist); ranlib must be applied to LIB afterwards. DLLs with data should be avoided if possible; they use undocumented features of EPOC and, if misused, need too much memory. ------------------------------------------------------------------------------ Find a symbol for a location: emxmap ------------------------------------------------------------------------------ {TODO} ------------------------------------------------------------------------------ Managing resource files: emxrsc / emxrsc.exe ------------------------------------------------------------------------------ emxrsc is a resource compiler similar to the SDK's rcomp; some features as well as lots of bugs of rcomp are missing in emxrsc. Note that emxrsc rejects invalid input with an error message instead of accepting errors silently and creating a bad binary resource file, as rcomp does. Floating point literals (for DOUBLE) are supported only if the host uses IEC 754 floating point arithmetic. To compile a resource file, call emxrsc this way: emxrsc [-P] [-D SYMBOL[=VALUE]]... -s FILENAME.rss [-o FILENAME.rsc] [-h FILENAME.rsg] (Note that rcomp does not allow a space between a switch and its argument and does not allow -o and -h to be omitted.) These switches are available: -h FILENAME.rsg Write the header file FILENAME.rsg defining names for the resource IDs. emxrsc won't rewrite the file if a file with equivalent contents already exists; this avoids unnecessary rebuilds of components depending on the header file -o FILENAME.rsc Write the binary resource file FILENAME.rsc; that file will be used on the EPOC device -s FILENAME.rss Read the resource source file FILENAME.rss -D SYMBOL=[VALUE] This switch is passed down to the C preprocessor -P Do NOT feed the source file through the C preprocessor (for rcomp compatibility) emxrsc can also be used to list the contents of a binary resource file: emxrsc [-a|-r] -d FILENAME.rsc [-o OUTPUT] These switches are available: -a Format the output such that it can be used as resource source file; attempt to interpret data as EIKON resources. Using this switch may violate licenses -d FILENAME.rsc Dump (list) the binary resource file FILENAME.rsc -o OUTPUT Write to the file OUTPUT instead of stdout -r Format the output such that it can be used as resource source file; data is not interpreted. Using this switch may violate licenses (Use emxaif for dumping the contents of a binary resource file used for generating an AIF file.) ------------------------------------------------------------------------------ Linker wrapper: eld / eld.exe ------------------------------------------------------------------------------ This is the linker wrapper which calls ld, dlltool, and emximage. All command line arguments which are not switches (or their arguments) are input files. The following switches are available: -acs Use alternative code checksum -allowdlldata Don't reject DLLs with data -e SYMBOL Override entry point -g Ignored -heap MAX Maximum heap size -heap-min MIN Minimum heap size -l LIB Search library LIB -L DIR Search directory DIR for libraries -o OUT Set filename of executable to OUT (default: a.out) -s Strip symbols -save-temps Do not delete intermediate files -shared Build a DLL -stack STK Set stack size -u SYMBOL Fake a reference to SYMBOL -uid# UID Set UID# (# is one of 1, 2, 3) -v Be verbose -Tdata ADDR Set data base address -Zdef DEF Write .def file DEF -Zexec DIR Search directory DIR for executables -Zexportdata LIST Export data from DLL, symbols listed in LIST -Zimplib LIB Create the import library LIB -Zlist List PECOFF executable -Zmap MAP Write map file MAP --help Dispay help message The -Zexportdata switch requires the -Zimplib switch. ------------------------------------------------------------------------------ Managing SIS files: emxsis / emxsis.exe ------------------------------------------------------------------------------ emxsis creates and dumps SIS files. Extracting files is not yet completely implemented. *** For creating a SIS file, call emxsis this way (like makesis): emxsis [-v] [-D SYMBOL=VALUE]... INPUTFILE.pkg [OUTPUTFILE.sis] If OUTPUTFILE.sis is omitted, emxsis will derive the name of the output file from the input file by replacing an existing suffix with ".sis" or by adding ".sis" if there's no suffix. The name of the input file can also be "-", in which case emxsis will read from standard input; the name of the output file must be specified. If a source file is not found and the EPOCROOT environment variable is set, emxsis tries again with the value of EPOCROOT (plus a slash, if required) prepended to the pathname of the source file. In some areas, emxsis is more fussy than makesis about the syntax of the .pkg file; in other areas, emxsis is less strict than makesis. *** To create a new .pkg file which differs from the original one only be the minor version number having been incremented by one, call emxsis this way: emxsis -i [-v] [-D SYMBOL=VALUE]... INPUTFILE.pkg OUTPUTFILE.pkg The name of the output filename must be specified; it's not possible to modify the .pkg file in place, so the two filenames must refer to different files (however, emxsis does not check for this situation). *** To dump (list) the contents of SIS files, call emxsis this way: emxsis -d [-8] [-c] [-f] [-l] [-p] [-q] [-v] INPUTFILE.sis... These switches are available: -8 Assume that characters having codes 0x20 through 0xff are printable. Without -8, characters having codes 0x20 through 0x7e are considered to be printable -c Check whether all bytes of the SIS file have been read (this is used for verifying emxsis) -d Dump a SIS file (without -d, emxsis will create a SIS file) -f For installed SIS files (in \system\install), check if the files exist and have the correct size. Example: emxsis -dfq c:/system/install/*.sis -l For installed SIS files (in \system\install), list the installed files -p Use the .pkg file format for the output file -q Display less information -v Display more information -D SYMBOL=VALUE Define the identifier SYMBOL to have the value VALUE, which must be an unsigned 32-bit number (hexadecimal numbers prefixed by "0x", octal numbers prefixed by "0"). The symbol SYMBOL can be used everywhere in the .pkg file where a number is expected. See the ER5 C++ SDK documentation on details about the format of .pkg files. *** To extract a file from a SIS file, call emxsis this way: emxsis -X INPUTFILE.sis FILENAME OUTPUTFILE FILENAME is the name of the file in the SIS file INPUTFILE.sis; it should match exactly one file (either its source file name or its destination file name). The pathname must match exactly. If found, the file will be written OUTPUTFILE (which will be overwritten if it already exists). *** To move all installed SIS files of one drive to the drive where they belong (where their files are supposed to be installed according to the SIS files), call emxsis this way: emxsis -m [-v] SOURCE_DRIVE: [TARGET_DRIVE:] This switch is available: -v Display more information The directory SOURCE_DRIVE:\system\install will be scanned for SIS files whose files are supposed to be installed on TARGET_DRIVE (if present) or on a drive different from SOURCE_DRIVE (if TARGET_DRIVE: is not present). For any such SIS file, you'll be asked whether the file should be moved to the drive where it belongs. If you answer "y", the file will be moved to the directory \system\install on the drive where its files are supposed to be installed. Example: emxsis -m c: d: This is useful if you have multiple CF cards; installed SIS files for applications installed on a CF card should be on that CF card to avoid confusion. emxsis does not check whether the files (of a SIS file) are really installed on the target drive. ------------------------------------------------------------------------------ Creating symbolic links: emxlink ------------------------------------------------------------------------------ This program is used to create "epocemx symbolic link files" under Unix for inclusion in SIS files. To create a symbolic link under EPOC, use the "ln -s" command of sh.exe. emxlink OLD NEW The file NEW will be created, containing a symbolic link to OLD. ------------------------------------------------------------------------------ Creating device files: emxmknod, mknod.exe ------------------------------------------------------------------------------ "emxmknod" is used to create "epocemx device files" under Unix for inclusion in SIS files: emxmknod PATH TYPE MAJOR MINOR "mknod.exe" is used under EPOC to create "epocemx device files" {currently, there's no mknod() system call}: mknod PATH TYPE MAJOR MINOR PATH is the name of the file; TYPE is either b (for a block device) or c (for a character device), MAJOR and MINOR are the major and minor device number, respectively. ------------------------------------------------------------------------------ Debugging panics: emxpanic.exe ------------------------------------------------------------------------------ This is a very experimental program; it just sits there and waits for any thread to panic; as soon as a thread panics, information about that thread is displayed. See also _emx_trap(). {TODO} ------------------------------------------------------------------------------ Building programs: make.exe ------------------------------------------------------------------------------ {TODO} A simple make tool for EPOC. Chaining of implicit rules is not implemented and emake is somewhat more fussy than other make tools. For now, see tools/emake.cc. ------------------------------------------------------------------------------ Command line shell: sh.exe / sh-acs.exe ------------------------------------------------------------------------------ A simple Unix-like shell for EPOC. Lots of features are missing. An Emacs-like command line editor with history (not saved in a file) provided by emx.dll. Here are some short notes {TODO}: This is a Unix-like shell, so use "/" instead of "\" in pathnames, or use quoting or escaping. See EmxConsole below for the keybindings of the line editor. Command line switches (see below for examples): -a Export all variables -c CMDS [ARG...] Execute commands CMDS -i Force interactive shell --cd DIR Change to directory DIR --login Force login shell --run CMD [ARG...] Execute command CMD with ARGs (used for builtins) --debug Enable debugging output You can start \bin\sh by running \emx.exe (a very small program -- put it into your favorite folders). Interactive login shells read $HOME/.profile (HOME is initially "/home"). You might want to put export LESS=-C into /home/.profile to improve the performance of less. As the default value of PATH does not include the current working directory, you have to prepend "./" to run a program from the current working directory unless you change PATH. C++ and OPL applications can be run by using the name of their application file: "editor.app Makefile". The \system\apps directories of drives E:, D:, C:, and Z: are searched for applications. Shell commands: if/then/elif/else/fi case/in/esac {patterns aren't expanded} for/in/do/done time until/do/done while/do/done ( ... ) { ... } Builtin commands: . : [ break cd continue cp {no -r option, -f is the default setting!} echo epocpath {given a Unix pathname, prints the EPOC pathname} eval exit export false function {no redir, not in background, not in pipeline} kill {be careful!} ln {only symbolic links, only two pathnames} mkdir {should be external, no -p option} mv {-f is the default setting!} ps {-m lists threads} pwd rm {should be external, no -r option} rmdir {should be external, no -p option} set {-a only} shift sleep source test true unset wait which {displays EPOC pathname with symlinks resolved} Redirections {no parameter expansion in FILENAME and NUMBER, only 0 through 2 can be used for NUMBER, all these redirections can be prefixed by 0 through 2, no << yet}: FILENAME >FILENAME >>FILENAME >&NUMBER Escape sequences in PS1 and PS2: \n \r \w \\ Special variables: HOME {no ~ expansion} {IFS is not implemented} OLDPWD PATH {see below} PS1 PS2 PWD Parameter expansion: $! $# $$ $* $? $@ $WORD $NUMBER ${all of the above} $'...' {no $"..."} Other expansions: ? * [...] {[...] is case-sensitive} {,} `cmd` {broken} $(cmd) {broken} Here are some examples which should point out the differences between the various ways to run the shell: sh /dev/tty a b c The first argument is the name of a shell script, so this example reads commands from the terminal. If you type "echo $2", the output will be "b" ($0 is "a"). sh -c 'echo $1;echo $2' a b c This will print "b" and "c" ($0 is "a"). sh --run echo a b 'c d' This will print "a b c d". There's no difference between sh.exe and sh-acs.exe, except for the code checksum. This is used to work around a bug in EPOC. If you delete sh-acs.exe, emx.dll will work around the problem by using emxrun.exe. If you also delete emxrun.exe, emx.dll will work around the problem by keeping zombies. ------------------------------------------------------------------------------ Listing directory contents: ls.exe ------------------------------------------------------------------------------ Switches of ls {sorry, no -R switch yet}: -1 One file per line (default if output is not a terminal) -a Don't omit files starting with "." -d List names of directories instead of the files they contain -l One file per line, additional information -m Multiple files per line, separated by ", " -n Ignored -p Like -F, but don't use "*" -r Reverse the sorting -t Sort by modification time (newest first) -C Multiple columns (default if output is a terminal) -F Append "/" or "*" -S Sort by size (biggest first) -U Don't sort (default: sort by name) -Z Use opendir() even under EPOC -- for debugging only --uid123 Show UIDs (a non-empty combination of 1, 2, 3 is required) ------------------------------------------------------------------------------ Dissecting pathnames: basename.exe and dirname.exe ------------------------------------------------------------------------------ {TODO} ------------------------------------------------------------------------------ Copying and concatening files to standard output: cat.exe ------------------------------------------------------------------------------ {This is cat.exe of emxshell.sis -- emxtextutils.sis contains GNU's version.} Switches of cat: -b Number non-empty lines -e Like -v -E -n Number all lines -s Display only one empty line for each sequence of empty lines -t Like -v -T -v Make control characters printable by prefixing ^ -E Display $ at end of line -S Ignore non-existent input files\ -T Display TAB as ^I ------------------------------------------------------------------------------ Showing disk usage: du.exe ------------------------------------------------------------------------------ Type "du -?" to get a list of available switches. Unfortunately EPOC conceals the filesystem's block size; use the -B option to set the block size for accurate results (the default value is 512). Bug: du follows symbolic links (which is a good thing for /c and /d). ------------------------------------------------------------------------------ Printing the environment: printenv.exe ------------------------------------------------------------------------------ {TODO} ------------------------------------------------------------------------------ Displaying UIDs: uidtool.exe ------------------------------------------------------------------------------ Type "uidtool -?" to get a list of available switches. ------------------------------------------------------------------------------ GNU awk ------------------------------------------------------------------------------ {TODO} awk.exe {no networking, no pipes} ------------------------------------------------------------------------------ GNU binary utilities ------------------------------------------------------------------------------ {TODO} ar.exe as.exe dlltool.exe ld.exe nm.exe objdump.exe ranlib.exe size.exe strings.exe ------------------------------------------------------------------------------ GNU diff utilities ------------------------------------------------------------------------------ {TODO} cmp.exe diff.exe {uses binary mode currently} diff3.exe sdiff.exe {editor does not work -- file in use} ------------------------------------------------------------------------------ GNU find utilities ------------------------------------------------------------------------------ {TODO} find.exe xargs.exe Hint: As /c and /d (and so on) are symbolic links (rather than mount points), you have to use find /c/ ... instead of find /c ... ------------------------------------------------------------------------------ GNU grep ------------------------------------------------------------------------------ {TODO} egrep.exe {uses binary mode currently} fgrep.exe {uses binary mode currently} grep.exe {uses binary mode currently} ------------------------------------------------------------------------------ GNU gzip ------------------------------------------------------------------------------ See [/usr]/man/gzip.1. {TODO} gzip.exe gunzip.exe zcat.exe ------------------------------------------------------------------------------ GNU recode ------------------------------------------------------------------------------ {TODO} recode.exe {quite big} ------------------------------------------------------------------------------ GNU sed ------------------------------------------------------------------------------ See [/usr]/man/sed.1. {TODO} sed.exe {uses binary mode currently} ------------------------------------------------------------------------------ GNU shell utilities ------------------------------------------------------------------------------ {TODO} date.exe {no timezone} echo.exe env.exe expr.exe factor.exe false.exe printf.exe seq.exe sleep.exe tee.exe test.exe true.exe tty.exe ------------------------------------------------------------------------------ GNU tar ------------------------------------------------------------------------------ {TODO} tar.exe {no compression} The z and I options are implemented for decompressing the input, but not for compressing the output. ------------------------------------------------------------------------------ GNU text utilities ------------------------------------------------------------------------------ {TODO} cat.exe {another one} cksum.exe comm.exe csplit.exe cut.exe expand.exe fmt.exe fold.exe head.exe join.exe nl.exe od.exe pr.exe ptx.exe sort.exe split.exe sum.exe tac.exe tail.exe {cannot interrupt "tail -f"} tr.exe tsort.exe unexpand.exe uniq.exe wc.exe ------------------------------------------------------------------------------ bzip2 ------------------------------------------------------------------------------ See [/usr]/man/bzip2.1. {TODO} Warning: bzip2 requires at least 7.5 MB of memory. bzip2.exe bzip2recover.exe ------------------------------------------------------------------------------ less ------------------------------------------------------------------------------ `less' is a better pager than `more'; it can be used for reading the manual pages in [/usr]/man. {TODO} less.exe man more.exe {a symbolic link to less.exe} zless ------------------------------------------------------------------------------ unzip and zip ------------------------------------------------------------------------------ See [/usr]/man/unzip.1 and [/usr]/man/zip.1. {TODO} unzip.exe zip.exe Note that this port of unzip and zip is derived from the Unix port and therefore does not support drive letters and other DOSisms and EPOCisms! ------------------------------------------------------------------------------ Managing object files and libraries: emxobj / emxobj.exe ------------------------------------------------------------------------------ This tool changes the name mangling of symbols in COFF/PE object files and libraries to reflect changes in GCC. It can also dump COFF/PE object files (but objdump is better at that). (To dump COFF/PE executable files, use objdump or emximage.) This line shows how to call emxobj to copy INPUTFILE (a COFF/PE object file or library) to OUTPUTFILE, remangling symbols in the process: emxobj [-n] [-m0|-m1] [-x EXPLICITFILE] INPUTFILE OUTPUTFILE These lines show how to call emxobj to create various text listings of a COFF/PE object file or library; output goes to standard output: emxobj -d INPUTFILE emxobj -e [-m0|-m1] INPUTFILE emxobj -i [-m0|-m1] INPUTFILE emxobj -p INPUTFILE... emxobj -r INPUTFILE... For testing emxobj, it can invoked this way to act as filter (reading from standard input, writing to standard output): emxobj -f [-c] [-m0|-m1] [-x EXPLICITFILE] [-D] Switches: -c In filter mode, only output those symbols which are changed by remangling -e Write an EXPORTS statement to standard output (this can be used to recreate a .def file for a DLL if you have the import library) -f Filter mode, read symbols (one per line) from standard input, write remangled symbols to standard output using the format "OLD -> NEW" -i Output an import list to stdout, see emxdump for the file format -d List (dump) the input file -m0 Don't remangle symbols -m1 Remangle symbols from GCC 2.7.2 960323 to GCC 2.97 20010205 (this is the default setting) -n Don't change symbols (equivalent to -m0, but invalid with -f) -p Find initialized and uninitialized data; emxobj tries to give hints (using some obscure output format) about the name of the offending objects and from where they are referenced -r Find suspect relocations, that is, references to symbols with a negative offset. This can be used to find out which part of the code triggers the message *** Value (...) at location to be fixed up (...) does not point into any section of emximage. However, emxobj may give false positives and it may miss the real culprit. -x FILENAME Read explicit mappings from the text file named FILENAME, each line should have the format "OLD -> NEW" -D Used for debugging emxobj emxobj is used by tools/install-epocsdk-headers, which in turn is invoked for target install-sdk of emxtool/Makefile. ------------------------------------------------------------------------------ Adapting SDK header files: emxfixhdr / emxfixhdr.exe ------------------------------------------------------------------------------ This program removes bugs of Symbian's ER5 SDK header files and makes them usable with later versions of GCC. It is called like this: emxfixhdr [-n] [SOURCE [DESTINATION]] If no filenames are specified, emxfixhdr reads from stdin and writes to stdout. If one filename (SOURCE) is specified, emxfixhdr reads from that file and writes to stdout. If two filenames are specified, emxfixhdr reads from SOURCE and writes to DESTINATION. If the -n switch is used, no changes are done, except for converting CRLF to LF. If the -n switch is not used, emxfixhdr modifies the contents of the lines while copying. emxfixhdr is used by tools/install-epocsdk-libs, which in turn is invoked for target install-sdk of emxtool/Makefile. ------------------------------------------------------------------------------ Disassembling: disasm ------------------------------------------------------------------------------ This program is used for testing the disassembler, but it can also be used for disassembling raw files such as sys$rom.bin. To disassemble EPOC executables, use emxdump, to disassemble object files, use objdump. The disassembler is far from complete. Using this program may violate licenses. ------------------------------------------------------------------------------ Installing EPOC files: emxinstall ------------------------------------------------------------------------------ Shell script for installing EPOC files. See INSTALL. ------------------------------------------------------------------------------ MISSING PROGRAMS ------------------------------------------------------------------------------ Programs not (yet) available: aleppo, bmconv, fnttran, fontcomp, makmake, pdrtran, etc., etc. Build steps involving these tools still need to be done using the ER5 C++ SDK; if you don't want to use Windows, see http://gnupoc.sourceforge.net. ------------------------------------------------------------------------------ EmxConsole ------------------------------------------------------------------------------ EmxConsole is an EIKON application which provides terminal emulation for a tree of processes. Output written to stdout and stderr by the client processes is displayed by EmxConsole. Keyboard input is redirected to that client process which reads from stdin. (As processes are usually started synchronously, at most one process at a time is reading from the console; asynchronous child processes cannot read from the console.) Important: Client processes continue to run if EmxConsole is terminated; client processes doing proper error checking will detect that EmxConsole is no longer running on their next access to the console (errno will be set to ENXIO). EmxConsole is also used to configure emx.dll (see menu "Tools"); you can configure these features: - drives on which symbolic links are to be supported (do not disable symbolic links on the drive where emx.dll is installed!) - number of lines the command line editor will remember - filename completion A line editor is used for reading from stdin. Keybindings (cf. Emacs): Key Function ------------------------------------------------------------------------- Enter End editing the line Left arrow Move left by one character Right arrow Move right by one character Down arrow Move to the next line in the history Up arrow Move to the previous line in the history Home Move to beginning of line End Move to end of line Del Delete the character to the left of the cursor Shift-Del Delete the character under the cursor Tab Simple filename completion (Shift-Tab to cycle backwards) Ctrl-D End editing the line or, if line is empty, EOF Ctrl-K Delete all characters under and to the right of the cursor Ctrl-Q Same as Ctrl-V Ctrl-U Delete all characters to the left of the cursor Ctrl-V Insert next (control) character verbatim Ctrl-W Delete spaces and the word to the left of the cursor Ctrl-Y Paste from the line editor's clipboard Note that EmxConsole intercepts Ctrl-Q and Ctrl-V unless reconfigured to use Shift-Ctrl-Q and Shift-Ctrl-V! The keys Ctrl-K, Ctrl-U, and Ctrl-W move the deleted characters to the line editor's clipboard. Note that Ctrl-Q and Ctrl-V are used by EmxConsole (unless EmxConsole is configured to use Shift+Ctrl instead of Ctrl for hotkeys), so they don't reach the line editor. EmxConsole emulates an ANSI/VT100 subset (n, x, and y are numbers): NUL Ignored BEL Make noise BS Move cursor left (wraps) TAB Move to next tab stop CR Move cursor to beginning of line LF Line feed {TODO: currently does CR automatically} CAN Reset mode SUB Reset mode ESC [ n A Move cursor up ESC [ n B Move cursor down ESC [ n C Move cursor right ESC [ n D Move cursor left ESC [ x G Move cursor to column x ESC [ y ; x H Move cursor ESC [ J Clear to end of screen ESC [ 2 J Clear screen ESC [ 0 K Clear from cursor to end of line ESC [ n L Insert lines ESC [ n M Delete lines ESC [ y d Move cursor to row y ESC [ n m Set mode (multiple n separated by ";" -- see below) Modes (for ESC [ n m): 0 Reset mode 4 Enable underline 7 Enable inverse 24 Disable underline 27 Disable inverse ------------------------------------------------------------------------------ EmxDevice ------------------------------------------------------------------------------ EmxDevice is an EIKON application which exists only to provide an icon for device files. Use the following commands of sh.exe to manage device files: mknod NAME TYPE MAJOR MINOR Create a device file ls -l NAME List a device file rm NAME Remove a device file ------------------------------------------------------------------------------ EmxLink ------------------------------------------------------------------------------ EmxLink is an EIKON application which exists only to provide an icon for symbolic links. Use the following commands of sh.exe to manage symbolic links: ln -s OLDNAME NEWNAME Create a symbolic link ls -l NEWNAME List a symbolic link rm NEWNAME Remove a symbolic link ------------------------------------------------------------------------------ \system\libs\emx.dll ------------------------------------------------------------------------------ emx.dll contains an implementation of spawn*() which does not limit command line arguments and lets child processes (which use emx.dll) inherit the current working directory, the file descriptors of the parent process, and the environment of the parent process. This works only for programs which are "emx applications", that is, programs which define main() and use emx.dll (as they were not linked with -Znoemx). Other programs can also be run by spawn*(), but the total size of command line arguments is limited and those progams won't inherit the current working directory, open file descriptors, etc. "emx applications" use EmxConsole for input and output. Child processes use the same EmxConsole instance as their parent process. In asynchronous child processes (P_NOWAIT), read() panics for attempts to read from the console. If P_NOTTYINPUT has been used, read() fails (EBADF) for attempts to read from the console. {TODO: If starting or connecting to EmxConsole fails, the standard console of EPOC will be used. The line editor, however, will still work (more or less, due to console bugs). Note that printing a TAB character which causes the cursor to move across the end of the line causes the program to hang. Note that the width of the console is not 80 characters unless EmxConsole is used. Running emx applications without EmxConsole should be done in emergency cases only.} The function _emx_trap(), declared in , installs an exception handler which, when the program crashes, may be able to display the location at which the program crashes. Various other information is available, see lib/emxtrap.cc. There's one major problem with _emx_trap(): if the exception is due to stack overflow, EPOC will reboot. See also emxpanic.exe. To use the global variable `environ', you have to #include . should be #included after the standard headers (as the SDK's uses `environ' as structure member). Compared to ESTLIB, libemx.a adds full or partial implementations of these functions: atol, fcntl, ffs, getopt, getprotobyname, getprotobynumber, getw, kill, lstat, mktemp, pathconf, pclose, pipe, popen, readlink, putw, spawnl, spawnle, spawnv, spawnve, spawnlp, spawnlpe, spawnvp, spawnvpe, symlink, sysconf, system, times, utime libemx.a adds these dummy functions: endgrent, endpwent, getegid, geteuid, getgid, getgrent, getgrgid, getgrnam, getpwent, getpwnam, getpwuid, getuid, raise, setgrent, setpwent, signal, umask libemx.a adds these emx-specific functions: _emx_trap, _emx_map_error, _emx_set_errno, _emx_parent, _epocpath, _samefile All this is subject to change. getcwd() may return a pathname of the form "/C:/System", that is, with a leading slash. This ensures that Unix programs know that it's an absolute path. Of course, pathnames of that form are acceptable to all library functions. send() and sendto() ignore their FLAGS argument. recv() and recvfrom() ignore all bits of their FLAGS argument except for MSG_PEEK. If you create your own version of emx.dll, please use a different name and different UID. ------------------------------------------------------------------------------ \system\libs\emxrun.exe ------------------------------------------------------------------------------ This program is used to work around a bug in EPOC, see spawn*(). ------------------------------------------------------------------------------ spawn*() ------------------------------------------------------------------------------ {TODO} There's a problem in EPOC: A program running another program which has the same code checksum (for instance, if it's the same program) will crash as soon as it closes the RProcess handle to the child process. To work around the problem, spawn*() does the following when it detects that the program to be run (child program) has the same code checksum as the parent: - If the filename of the child program does not end with "-acs" (preceding the extension), "-acs" will be added, otherwise removed. For instance, "sh.exe" becomes "sh-acs.exe" and vice versa. If there's an executable having that filename and having a code checksum which is the one's complement of the original code checksum, that executable will be run. See the -acs switch of emximage and the sh-acs.exe target of tools/Makefile. - If the above fails, spawn*() tries to run emxrun.exe which is supposed to live in the same directory as emx.dll. emxrun.exe will then run the the child program. If emxrun.exe cannot be found or if emxrun.exe has the same code checksum as the child program, spawn*() will fall back to the last resort: - If all of the above fails, spawn*() will not close the RProcess handle to the child process, resulting in a resource leak and zombies. ------------------------------------------------------------------------------ Environment variables ------------------------------------------------------------------------------ For programs which are not started by spawn*(), the environment will contain these variables: PATH=/bin:/usr/bin HOME=/home Please don't put paths containing drive letters into PATH as ":" is used as separator. Instead, use symbolic links: ln -s d:/mybin /mybin PATH=$PATH:/mybin Some programs use the directory pointed to by the TMPDIR environment variable for temporary files. You may want to let it point to a CF card to save real memory. ------------------------------------------------------------------------------ Common problems ------------------------------------------------------------------------------ If running a program under EPOC causes a dialog box of this form to be displayed: Program closed ---------------------- Program: ... Reason code: LDR-IMPORT Reason number: 2 your emx.dll is probably outdated. Please install the latest version. ------------------------------------------------------------------------------ Thanks ------------------------------------------------------------------------------ I wish to thank Ondra Cada, Fritz Elfert, Olaf Flebbe, Alfred E. Heggestad, Tomas Hurka, Rudolf König, Philip Proudman, and Matt Williams. ------------------------------------------------------------------------------ Your help is needed ------------------------------------------------------------------------------ EmxConsole, EmxDevice and EmxLink are in desparate need of nice icons (they should be available under the GPL). A port of epocemx to ER6 (Symbian OS) would be nice. ------------------------------------------------------------------------------ Pointers ------------------------------------------------------------------------------ epocemx home site: http://epocemx.sourceforge.net ------------------------------------------------------------------------------ Future plans ------------------------------------------------------------------------------ Replace CEikConsole to be able to implement Edit->Copy and scrolling with the keyboard (and for getting rid of bugs). Implement O_TEXT and O_BINARY (currently, O_BINARY is used for all files; this may or may not change in the future, so please always specify O_TEXT or O_BINARY (or "b" or "t" for fopen)). Fully support sockets (e.g., non-blocking sockets, getsockopt, setsockopt). Support I/O, wait(), etc. for multithread programs. Provide more clones of ER5 C++ SDK tools. Backport GCC bug fixes. Remove the preprocessor from cc1 and cc1plus to save memory. Try to reduce the memory requirements of cc1plus to make it really work on the PSION 5mx PRO. Replace dlltool (which is incredibly slow under EPOC because it calls "as" and "ar") and use a sane format for import libraries (the EPOC import libraries are incredibly big). Improve esh. Port some essential Unix tools. WTFM. Make the tools more EPOC-friendly (don't crash when out of memory). Fix the Mtools and Linux bugs/features mentioned in INSTALL. ============================================================================== END ==============================================================================