Category : OS/2 Files
Archive   : GNUDEV8F.ZIP
Filename : GNUDEV.DOC

 
Output of file : GNUDEV.DOC contained in archive : GNUDEV8F.ZIP
===============================================================================
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
([email protected]).

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 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 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 ------------------------------


  3 Responses to “Category : OS/2 Files
Archive   : GNUDEV8F.ZIP
Filename : GNUDEV.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/