OS/2 Professional

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / emx / doc / gnudev.doc < prev next >

Wrap

Text File | 1993-01-03 | 25.2 KB | 753 lines

=============================================================================== gnudev.doc emx 0.8f GNU DEVELOPMENT TOOLS INFORMATION 03-Jan-1993 =============================================================================== Table of Contents ================= 1 Introduction 2 GCC -- compiling and linking C and C++ programs 2.1 Calling GCC 2.2 Environment variables 2.3 #pragma 2.4 Additional command line options 2.5 C++ 2.6 Objective C 2.7 Stack probes 2.8 Other changes 2.9 Calling conventions 3 libg++ -- the GNU C++ library 4 GDB -- debugging 5 GAS -- assembling 6 ld -- linking 7 ar -- managing library files 8 ranlib 9 nm -- listing symbols 10 strip -- removing the symbol table 11 info -- browsing info files 12 makeinfo -- creating info files 13 texindex -- creating index for printed manual 14 termcap -- terminal capabilities 15 readline -- input editing 16 Known problems 1 Introduction ============== This text describes how to use the GNU C Compiler and other GNU utilities with emx. See emxdev.doc for instructions for the emx utilities. For details information about GCC and GDB, read the GCC and GDB manuals, see install.doc. See build.doc for details on compiling the GNU utilities. All the programs assume that the entire package is installed on one disk drive in these directories: /emx/bin Executable files /emx/etc termcap.dat /emx/lib Library files /emx/include Include files If the /emx directory is not on the current drive, use the C_INCLUDE_PATH and LIBRARY_PATH environment variables, for instance set C_INCLUDE_PATH=c:/emx/include set LIBRARY_PATH=c:/emx/lib to use drive C. Use forward slashes instead of backward slashes in path names! Directories: /emx Main directory, empty /emx/bin Executable files and batch files /emx/doc Documentation /emx/etc termcap.dat /emx/gnu/bfd Binary File Descriptor library (for GDB) /emx/gnu/binutils GNU utilties for binary files (sources) /emx/gnu/gas-1.38 GNU assembler source /emx/gnu/gcc-2.3 GNU C compiler source /emx/gnu/gdb-4.7 GNU debugger source /emx/gnu/include Header files for GCC (C language) /emx/gnu/include.cpp Header files for GCC (C++ language) /emx/gnu/libibert -liberty (for GDB) /emx/gnu/readline Readline library (for GDB) /emx/gnu/termcap GNU termcap /emx/include C header files /emx/lib Libraries 2 GCC -- compiling and linking C and C++ programs ================================================= GCC 2.3.3 has been ported to emx. 2.1 Calling GCC --------------- Example: gcc -o test.exe test.c This assumes that emxl.exe can be found in one of the directories listed in the EMXPATH and PATH environment variables, or in the directory /emx/bin, see also ld. If the output file name doesn't end in `.exe', the output file will have a.out format. Please note that the example given above creates a file named `test' which will be deleted after converting to .exe format. 2.2 Environment variables ------------------------- If you want to develop programs on a drive different from the drive where emx is installed, you have to set the C_INCLUDE_PATH and LIBRARY_PATH environment variables, for instance, set C_INCLUDE_PATH=c:/emx/include set LIBRARY_PATH=c:/emx/lib If you want to compile C++ programs, set CPLUS_INCLUDE_PATH as well: set CPLUS_INCLUDE_PATH=c:/emx/include.cpp;c:/emx/include The genclass utility needs the following environment variable: set PROTODIR=c:/emx/include.cpp/gen If the TMPDIR environment variable is not set, temporary files are written to the current working directory. For instance, use SET TMPDIR=f:/tmp/ to put temporary files into the F:/TMP directory. 2.3 #pragma ----------- The emx port of GCC supports #pragma pack(n) where n is 1, 2 or 4. The default is 4. Structure fields are aligned to multiples of N bytes, according to the value N as set by the last #pragma pack statement. #pragma pack() reverts to the default (4). 2.4 Additional command line options ----------------------------------- Several command line options have been added to GCC: -mprobe, -mno-probe, -Zdll, -Zmt, -Zomf, -Zsys and -Zwait. -mprobe enables generation of stack probes (see below), -mno-probe (which is the default) disables generation of stack probes. The additional GCC command line option -Zomf causes GCC to call emxomf for converting .o files to .obj files and to call emxomfld instead of ld. As emxomfld calls LINK386, this option works only under OS/2. Note that LINK386 adds a default extension (.EXE or .DLL) to the output file name. Use the option -T 0x10000 to create non-relocatable .EXE files, which are slightly smaller and load slightly faster. Use -Zsys with -Zomf to link with the system call library (emx emulator) libsys.lib instead of using the run time library emx.dll for system calls. The library version of the system calls provide only a subset of the emx system call interface. The additional GCC command line option -Zdll links with dll0.o (or dll0.obj if -Zomf is given) instead of crt0.o. This is required for creating dynamic link libraries. Use the additional GCC command line option -Zmt to link a program that uses emxlibc.dll, the DLL version of the C library. The preprocessor macro __MT__ will be defined when -Zmt is used. The additional GCC command line option -Zwait causes the assembler to be called with the -w option to automatically insert `wait' instructions. As all numeric exceptions are masked, this is currently not required. You can give the name of a module definition file on the command line. The name must end with .def and is passed to ld, which in turn passes it to emxbind. When using -Zomf, the name is passed to emxomfld, which in turn passes it to LINK386. If the output file names ends with .dll, a default module definition file is used by emxbind unless a .def file is given on the GCC command line. You can give the name of a binary resource file on the command line. The name must end with .res and is passed to ld, which in turn passes it to emxbind. When using -Zomf, the name is passed to emxomfld, which runs RC to copy the resources to the output file. The following table shows the startup module and the libraries passed to the linker by GCC, depending on the command line options -Zomf, -Zsys and -Zdll: Options | Startup | Libraries -----------------------+----------+-------------------------------- (none) | crt0.o | libgcc.a libc.a libemx1.a -Zdll | dll0.o | libgcc.a libc.a libemx1.a -Zomf | crt0.obj | libgcc.lib libc.lib libemx1.lib -Zomf -Zdll | dll0.obj | libgcc.lib libc.lib libemx1.lib -Zomf -Zsys | crt0.obj | libgcc.lib libc.lib libsys.lib -Zomf -Zsys -Zdll | dll0.obj | libgcc.lib libc.lib libsys.lib -Zmt | crt0.o | libmt.a -Zmt -Zdll | dll0.o | libmt.a -Zmt -Zomf | crt0.obj | libmt.lib -Zmt -Zomf -Zdll | dll0.obj | libmt.lib The OS/2 import library libos2.a or libos2.lib is always passed to the linker. The import library for emx.dll, libemx2.a or libemx2.lib, is passed to the linker unless -Zsys is used. 2.5 C++ ------- C++ programs should have a `.cc' file extension. Use the -lgpp command line option to link C++ programs. Example: gcc -o hello.exe hello.cc -lgpp -s The `collect' program is not required with the emx port of GCC. Hint: Use the -s option (of GCC or emxomf) to remove the symbol table; it's quite big. 2.6 Objective C --------------- To link a program written in the Objective C language, you have to use the libobjc library: use -lobjc on the GCC command line. Example: gcc -o objcsamp.exe objcsamp.m -lobjc -s Note that GCC does not include any class libraries. 2.7 Stack probes ---------------- Stack probes are used to manage automatic stack growth if the stack is not completely committed. When allocating stack space, the new stack pages are touched before changing the stack pointer to make them accessible. Generation of stack probes is disabled by default. Use the -mprobe option to enable generation of stack probes. You need stack probes if - you use DosCreateThread to create a thread that doesn't have a completely committed stack, that is, if bit 1 of the ulThreadFlags argument is zero, or - your program uses emx.dll and the size of the stack object is 16 KB or smaller (in this case, a new stack object is allocated and managed by emx.dll) -- which is not recommended, or - you want to trap the stack overflow exception issued when hitting the guard page at the bottom of the stack. Stack probes are not generated for all allocations of stack space: A stack probe is not generated if the size is constant and less than 4096 bytes. This optimization causes a problem if two such allocations of stack space occur without access to the stack between the allocations. There are two occasions for this: Two calls in a row to alloca() with constant argument which is less than 4096 and where nothing is stored to the first pointer returned by alloca() before getting the second pointer: p = alloca (0xf00); q = alloca (0xf00); The second case is a function with less than 4096 bytes of local data which calls alloca() with constant argument which is less than 4096 before accessing a local variable or calling a function: void test (void) { char local[0xf00], *p; p = alloca (0xf00); /*...*/ } As both cases are unlikely to occur in practise, I chose to not generate a stack probe for less than 4096 bytes. If you experience problems (that is, stack exceptions), insert the statement {char *p=alloca (0); *p = 0;} in critical places, as between the two alloca() calls in the first example and before the alloca() call in the second example. All libraries for emx are compiled with stack probes enabled. 2.8 Other changes ----------------- The preprocessor CPP defines the symbols __32BIT__ and __EMX__. If the -Zmt option is given on the GCC command line, the symbol __MT__ is defined. The file name extensions of the debugging output files (-d option) have been changed as follows: combine -> cmb cse -> cs1 cse2 -> cs2 flow -> flo greg -> gre jump -> jp1 jump2 -> jp2 loop -> loo lreg -> lre sched -> sd1 sched2 -> sd2 stack -> stk The extension is added to the base name of the input file, not to the complete name of the input file. For instance, when compiling world.c, the file world.cs1 will be created instead of world.c.cse. If using the -da GCC option, you should use the -h30 emx option. 2.9 Calling conventions ----------------------- The calling convention used by GCC is almost compatible with the `system' calling convention of IBM C Set/2. Structures are returned differently: IBM C Set/2 uses a hidden parameter which is removed from the stack by the caller, GCC returns the structure in registers EAX and EDX if its size is 8 bytes or less. GCC uses a hidden parameter if the size of the structure is more than 8 bytes, but the callee removes the hidden parameter from the stack. Currently, the GCC option -fpcc-struct-return doesn't solve that problem. Instead, rewrite the function and the function call as follows: Original code: -------------- struct s1 func1 (int a1) { struct s1 t1; ... return (t1); } ... struct s1 v1; v1 = f1 (0); Modified code: -------------- struct s1 *f1 (struct s1 *ret, int a1) { struct s1 t1; ... *ret = t1; return (ret); } ... struct s1 v1; f1 (&v1, 0); 3 libg++ -- the GNU C++ library =============================== libg++, the GNU C++ library, has been ported to emx by Kai Uwe Rommel (rommel@jonas.gold.sub.org). If you're linking with libg++, (-lgpp), you have to obey the rules of /emx/doc/copying.lib. Due to name collisions, the following include files have been renamed: Complex.h -> Complx.h Regex.h -> Regx.h String.h -> Strng.h All *.C files have been renamed *.cc. Moreover the following source files have been renamed: Complex.C -> Complx.cc (/emx/gnu/libg++/src) Regex.C -> Regx.cc (/emx/gnu/libg++/src) String.C -> Strng.cc (/emx/gnu/libg++/src) Filebuf.h -> Filebuff.h (/emx/gnu/libg++/old-stream) Filebuf.C -> Filebuff.cc (/emx/gnu/libg++/old-stream) Dirent.h -> Direntr.h (/emx/gnu/libg++/etc/lf) Dirent.C -> Direntr.cc (/emx/gnu/libg++/etc/lf) 4 GDB -- debugging programs =========================== GDB uses readline, see below. GDB works only with a.out files and bound files, not with arbitrary DOS or OS/2 progams. Example (debug myprog.exe): C> gcc -g -o myprog.exe myprog.c (compile) C> gdb myprog.exe (start debugger) (gdb) b main (set breakpoint) (gdb) run (start program) (gdb) s (step) Don't use backslashes in path names. The following GDB commands do not work or do not work completely or have been changed: - `signal' does not work - `handle' is not tested and won't work - `attach' and `detach' cannot work - `tty' and `term-status' are not implemented - `directory' has been changed to use semicolons instead of colons for separating directories. - `watch' is almost unusable because GDB disables the watchpoints as soon as a function without debugging symbols is called, such as the system calls. That could be fixed by making GDB believe that the functions in syscalls.s have debugging symbols and making ptrace(9) catch calls to __syscall. Continuing debugging after the debuggee got a signal currently does not work: one of the problems is that ptrace() and GDB don't know about segmenting. Debugging multi-threaded programs is not yet possible. If you want to run the debuggee in the same OS/2 session (window) as GDB (for instance if you're running GDB in a full-screen session), use the -E emx option. This is also required for earlier OS/2 2.0 releases. By default, GDB selects the child session when executing a CALL instruction of the inferior process. Use the `set switch off' command to disable that feature. Use `set switch on' to turn on switching to the child session. Use `show switch' to display the current setting. Under DOS, `set switch' is ignored. To debug a Presentation Manager application, run GDB full-screen and use `set switch on'. Do not switch to the Presentation Manager session while the program is stopped! Otherwise the Presentation Manager will hang. As import method (I1) uses a JMP instruction instead of a CALL instruction to call OS/2 API functions, the `stepi' command must not be used to step into the code generated by emximp for a method (I1) import. Use `nexti' on the call to that code, instead. Use the `set close' command to control whether to close the child session window after termination of the debuggee. `set close off' is the default -- the window will stay open. After the debuggee has been started, `set close' doesn't take effect. The .gdbinit file has been renamed !gdbinit. To save typing, you might want to create a file named !gdbinit in the directory where you're debugging. Here's an example of a !gdbinit file: file myprog.exe set arg -o test.out test.inp b main set close on run set switch off Hint: to debug an .exe file which doesn't have a symbol table use the symbol table from the a.out file and type gdb -e myprog.exe -s myprog You can do post-mortem debugging by using the `core' file written by emx when a program aborts. You can use the following redirection specifications with `set args': <filename Redirect the file named FILENAME to stdin >filename Redirect stdout to the file named FILENAME, overwriting >>filename Redirect stdout to the file named FILENAME, appending You can prepend a handle number (0 to 9) to such a redirection specification; for instance 2>filename redirects stderr to FILENAME. Quoting with quotation marks is not (yet) implemented. Example: set args first_arg second_arg <input >output 2>error 5 GAS -- assembling =================== GAS is the GNU assembler. The executable file name of GAS is as.exe. The emx port of GAS includes an additional command line option: -w instructs GAS to insert a wait instruction if a 387 instruction (beginning with `f') is followed by a 386 instruction (not beginning with `f'). The wait instruction is not required as all numeric exceptions are masked. 6 ld -- linking =============== ld is the GNU linker. If the output file has an .exe or .dll extension, emxbind will automatically be called to bind emxl.exe and the a.out file into an .exe or .dll file. The output file name without .exe or .dll extension is used for the a.out file which will be deleted after converting to .exe or .dll format. emxl.exe is sought in the directories listed in the EMXPATH and PATH environment variables, and in /emx/bin. See /emx/gnu/binutils/ld.c for command line options. ld is usually called only by GCC, not from the command line. The -s option (strip symbols) is passed on to emxbind. If ld doesn't call emxbind, ld will strip the symbol table. Unfortunately, ld doesn't correctly strip the symbol table. This port of ld supports an additional command line option: -R for creating relocatable executable files. -R is automatically set if the output file has a .dll extension. -R is also automatically set if an import definition of type (I2) is referenced. This is used to import functions from dynamic link libraries. If you link with import definitions of type (I1), you have to manually supply the -R option. If a file name with .def extension is given on the ld command line, it will be passed as module definition file (-d option) to emxbind. If there is no .def file on the command line and the output file is a .dll file, the -d option without argument is passed to emxbind; emxbind will use the name of the output file (with .def extension) for the module definition file. If a file name with .res extension is given on the ld command line, it will be passed as resource file (-r option) to emxbind. Note that the sequence of .o and .a files and -l options is essential. crt0.o or dll0.o must come first. Libraries are considered only once, that is, if a library references symbols defined in another library, the former one must be used before the latter one. If library lib1.a uses library lib2.a, which in turn uses library lib1.a, you have to use -l1 -l2 -l1. 7 ar -- managing libraries ========================== `ar s' won't work if the archive already contains __.SYMDEF. Use `ar d mylib.a __.SYMDEF' first. `ar q' doesn't work due to file sharing problems (Unix hacks in ar). Use `ar r' instead. See /emx/gnu/binutils/ar.c for command line options. ar supports response files and wildcards on the command line. See the makefiles in emxlib.zip for examples. 8 ranlib ======== Not available. `ar s' is used instead. 9 nm -- listing symbols ======================= Lists symbols of an a.out or bound .exe file. As there is no manual, read /emx/gnu/binutils/nm.c for command line options. A command line option has been added: -d don't demangle C++ symbols (long name: +no-demangle) 10 strip -- removing the symbol table ==================================== strip is used to delete symbols from an a.out file. It cannot be applied to bound .exe files. See /emx/gnu/binutils/strip.c for command line options. See also emxbind (-s command and -s option). 11 info -- browsing info files ============================== Before using info, you have to install termcap. This is done by setting the TERM environment variable and one of the following environment variables: INIT, EMXETC, TERMCAP. Here's an example: set term=mono set termcap=c:/emx/etc/termcap.dat Then, you have to set the INFOPATH environment variable. It's a list of directories, separated by semicolons. The /emx/info directory should be included. Example: set infopath=c:/emx/info If the INFOPATH environment variable is not set, the following list of directories will be used: .;/emx/info;/emacs/info After setting all the environment variables, you can run info by typing info Type ? to get a short list of keys. Type H to invoke the tutorial. In addition to the standard keys, the following keys are supported: Addition key Original key Description ------------------------------------------------ F1 ? List of commands UP, BACKTAB N/A Move to previous menu choice DOWN, TAB N/A Move to next menu choice RETURN N/A Select highlighted menu choice C-HOME d Move to the directory node LEFT p Move to the previous node RIGHT n Move to the next node C-UP u Move up from current node C-DOWN f Follow a cross reference PAGEDOWN SPACE Scroll forward a page PAGEUP DEL Scroll backward a page HOME b Go to the beginning of the node Press the BACKSPACE key to generate the DEL code. If the TERM environment variable is not set, info asks for the terminal type but doesn't work correctly. Always set TERM. 12 makeinfo -- creating info files ================================== makeinfo creates info files from texinfo files. Type makeinfo to get a list of options. When splitting files, makeinfo uses the extensions i01, i02, ..., i99. 13 texindex -- creating index for printed manual ================================================ texindex sorts the index for typesetting a texinfo file with TeX. To compile a texinfo file under OS/2, simply move to the directory where the source file resides and enter texi2dvi filename where filename is the name of the source file. Example: cd \emx\gnu\texinfo texi2dvi texinfo2.txi texi2dvi is a REXX procedure which calls TeX and texinfo. See the first two statements of /emx/bin/texi2dvi.cmd for customization. 14 termcap -- terminal capabilities =================================== For using termcap, you have to put termcap.dat in the current working directory, into directory /emx/etc on the current drive, or into a directory listed in the INIT or EMXETC environment variables. You can also set the TERMCAP environment variable to contain the absolute path name of termcap.dat. If the TERM environment variable isn't set, ansi will be used (ANSI.SYS required). Otherwise, the terminal given in the TERM environment variable will be used. I recommend using mono. See termcap.dat for details. To link a program with the GNU termcap library, specify -ltermc on the GCC command line. Read the license in /emx/gnu/termcap/termcap.c or /emx/doc/copying! 15 readline =========== The standard Emacs/readline key bindings are used with the following exceptions and additions: BS, C-H rubout HOME beg_of_line END end_of_line UP get_previous_history DOWN get_next_history LEFT backward RIGHT forward PAGEUP beginning_of_history PAGEDOWN end_of_history DELETE delete C-LEFT backward_word C-RIGHT forward_word C-HOME backward_kill_line C-END kill_line The readline library source comes with the GDB source files. 16 Known problems ================= - the -s option of GNU ld doesn't work correctly -- nm etc. don't work on files created by ld if the -s option is used - GCC 2.3.3 cannot pass more than 24 (temporary) files derived by the GCC command from source files to the linker - info doesn't work correctly if the TERM environment variable is not set - GCC 2.3.3 fails to generate line number information for loops of the following type: for (i = 0; i < 100; ++i) do_something (i); You cannot step into the loop; the complete loop will be executed instead of one iteration. A workaround is to rewrite the code as follows: for (i = 0; i < 100; ++i) { do_something (i); } --------------------------- END OF GNUDEV.DOC ------------------------------