Go to the first, previous, next, last section, table of contents.


7 Usage

[Details under construction]

This chapter describes the usage of various parts of Geek Gadgets.

7.1 Initial problems

This section tries to cope with those problems known to arise for almost everyone starting to use Geek Gadgets. If you stumble about other things, please discuss them with the Geek Gadgets mailing lists. See section 1.1 Mailing Lists.

7.1.1 Stack size

Many Geek Gadgets tools require large amounts of stack space. Some of them have been compiled to automatically grow the stack as necessary, but the work to build all of them with automatic stack expansion is not yet complete. Thus you need to take care to set an appropriate amount of stack. One way to do this is to add a line like:

stack 200000

to your S:User-Startup file. There are various opinions about what the minimum stack size should be. You could get away with as little as 50K in some circumstances, or need over 500K in others. Random crashes, irreproducible behavior, machine lockups, and other such problems are typical symptoms of setting the stack too low.

An alternate way to specify a larger stack on a per program base is the use of ixstack. Starting with ixemul-44.0, ixstack can be used on a program to set the stack allocated by ixemul.library when starting a new section 7.2.3 ixemul program.

Recommended stack sizes for use with ixstack:

pdksh
50KB, upto 128KB if using a very large `config.cache' file like the one from `GG:etc/'
GCC
is compiled with `-mstackextend' now, but used to require from 50KB to 800KB depending on the source file
GNUEmacs
40KB, some people seem to need more
man
32KB recommended for man since `manutils-2.x'. man can call groff, see below
groff
64KB recommended by Rask Ingemann Lambertsen rask@kampsax.dtu.dk
sed
128KB recommended by Lars Hecking lhecking@nmrc.ucc.ie otherwise some configure scripts crash the machine

Please send suggestions about stack sizes to Fred Fish fnf@ninemoons.com

7.1.2 Hello World

OK, what about a nice Hello World ?

#include <stdio.h>

main()
{
	printf("Hello World!\n");
}

This was pretty simple ;-) Now we have to compile it. There's a lot of options in GCC but the simplest way to compile this would be:

CLI> gcc -o hello hello.c

Simple?

Here's more options.

Target processor for Motorola family: You can compile plain 68000 code, 68020, 68030, 68040, 68881 (have a look at GCC documentation, either in info or AmigaGuide format, chapter Invoking GCC/SubModel Options/M680X0 Options for Motorola specific compilation flags).

CLI> gcc -m68020 -m68881 -o hello hello.c

This will compile your programs using 68020 code and direct calls to math-processor, and will link with accelerated libraries, located in GCC:lib/lib020.

Optimization: Either you don't want optimization, or you can provide -O, which will optimize your code, or if you really want top optimization, use -O2 flag (for more discussion about optimization, read info or AmigaGuide doc chapter Invoking GCC/Optimize Options). There's now even a -O3 optimization option, which will go even further.

CLI> gcc -O2 -o hello hello.c

You'll never have a "Hello World" program running so fast ;-)

Code generation: Perhaps you want to generate resident programs. Flag is -resident, at compile and link stage.

CLI> gcc -resident -o hello hello.c

Of course you can mix all options, resulting in:

CLI> gcc -O2 -m68020 -m68881 -resident -o hello hello.c

This will make a 68020+68881 executable highly optimized and resident.

IMPORTANT: If you only use Amiga OS functions or you don't want to use ixemul for philosophical reasons, you can get rid of ixemul.library with:

CLI> gcc -noixemul -o foobar foobar.c

provided you have libnix distribution (included with 2.6.0 and up distributions).

7.1.3 Hello Amigaworld

OK, what about another nice Hello World using AmigaOS?

/*  Compile this example with
	gcc -noixemul -o HelloWorld HelloWorld.c
*/
#include <stdlib.c>
#include <intuition/intuition.h>
#include <proto/intuition.h>

int main(int argc, char *argv[])
{
	struct EasyRequest er;

	er.es_StructSize = sizeof(er);
	er.es_Flags = 0;
	er.es_Title = "Message";
	er.es_TextFormat = "Hello, world!\nintuition.library is at 0x8l.";
	er.es_GadgetFormat = "Ok";
	EasyRequest(NULL, &er, NULL, IntuitionBase);
	exit(0);
}

Some notes:

7.1.4 Ixemul vs. Libnix

Starting with 2.6.1 version of AmigaOS GCC, two C libraries are provided.

First one is using ixemul.library Amiga shared-library at run-time. This library makes it possible to easily convert Unix(tm) programs to AmigaOS, and made GCC possible on AmigaOS, for example. See section 7.2.3 ixemul.

Second one is an ANSI-C compliant library which is better suited for AmigaOS specific development, thus not using any Unix specific routines. Libnix is a static (i.e. link) library for GCC 2.3.3 or above. It's not a replacement for ixemul.library (though it's possible to recompile most of the GCC environment with libnix) but a good thing for Amiga specific development on GCC. See section 7.2.6 libnix.

Note that you can develop AmigaOS specific programs with ixemul.library, but at the cost of an extra 200 kB of memory taken by shared library.

To cut it short:

Use ixemul.library for porting Un*x programs, libnix for compiling amiga-only programs and gcc becomes one of the best Amiga compilers.

7.1.5 Memory shortage

Some Geek Gadgets tools (i.e. gcc) are often (but not always) memory hungry, a few tricks to save memory can make life easier:

7.1.6 Storage shortage

A Geek Gadgets installation may well need lots of space on your storage media, a few tricks to save storage can make life easier:

7.1.7 SAS/C => GNU/C

[Details under construction]

It is possible to link object files that were created by different conpilers, specifically GNU/C and SAS/C, as follows:

One problem with this approach would be with floating point code and with integer multiplication/division. To surround this problem you can either compile your SAS/C programs with CPU=68020 (or higher) and MATH=68881 to make SAS/C produce inline code. Or you will have to grab the necessary modules from the SAS/C libraries and convert them to aout object format as well.

7.2 Package topics

This section summarizes informations concerning specific programs or packages.

Of course, almost every package comes with a documentation of its own, which is the primary source of information. But there's often the need to give some extra informations which doesn't fit into this documentation for various reasons, such as:

7.2.1 gcc

[Details under construction]

Please refer to the gcc-amigaos documentation for further details on the AmigaOS specific features of gcc. See section `Top' in The GCC-AmigaOS Manual.

Please refer to the gcc documentation for further details on gcc. See section `Top' in The GCC Manual.

7.2.2 gnat

If you download a copy of the Gnat archive in .tgz format, you must take into consideration the problems with the datestamps. The datestamps allow the ada compiler to see if a package has been modified. The compiler will recompile any package if it has been modified.

If you just unpack the archive, the datestamps on the ada packages will be wrong and you will need a lot of memory to recompile the entire set of packages (> 8MB). To avoid this you must set the timezone to the correct offset.

If you downloaded the archive from ftp://ftp.ninemoons.com/pub/geekgadgets or one of its mirrors, you will need to use the MST timezone. If you downloaded the recent archive from ftp://ftp.idiom.com/users/ocremel/, you will need to use the PST8 timezone. The latter version of Gnat has not been included into Geek Gadgets yet, and thus the version of GCC that is installed as part of Gnat is different to the version of GCC from Geek Gadgets in that it will not find the linker ld if executed from within a normal Amiga Shell.

In the Amiga shell type the following:

To decompress gnat with the datestamps correct...

	copy gnat.tgz to gg:
	setenv TZ PST8 or MST
	ixtimezone -get-offset
	tar -xzvpf gnat.tgz

Reset the timezone for your machine...

	setenv TZ (local timezone)
	ixtimezone -get-offset

The following environment variables need to be added to the GG-startup script in gg:sys/s/ for Gnat to work properly:

	setenv ADA_INLUDE_PATH /gg/adainclude
	setenv ADA_OBJECTS_PATH /gg/lib/gcc-lib/m68k-amigaos/2.7.2.1/adalib

You may have more than one path in these environment variables. If you do, however, separate them with a colon in the normal unix fashion.

Test the compiler with the following code:

with Text_Io ;
use Text_Io ;

procedure Hello is

begin

  Put ( "Hello! This is your computer speaking." ) ;

end Hello ;

Run the compiler like this (NOTE: gnat must be run from within a unix shell, This will avoid an EMT trap error):

2.Work:Downloads/ada>sh
$gnatmake hello
$hello
Hello! This is your computer speaking.
$

7.2.3 ixemul

[Details under construction]

This library was developed by Markus Wild when originally started porting GCC (up to version 2.3.3). It is a shared library that emulates a lot of Un*x functions, making life a lot easier for folks porting GNU utilities and such. Unfortunately, it is fairly resource hungry by Amiga standards, and has caused not a little irritation among Amiga users. By default, programs compiled by GCC open ixemul.library, so if you want to avoid it, you'll have to use `-noixemul' on the command line (see below in Amiga specific extensions and/or coding with libnix) and link to one of the libraries below.

For an introduction and a comparison, see section 7.1.4 Ixemul vs. Libnix.

You can use the ixprefs program to set various options of ixemul.library. Please refer to the ixprefs documentation for further details. See section `Top' in The Ixprefs Manual.

Please refer to the ixemul documentation for further details. See section `Top' in The Ixemul Manual.

7.2.4 java

The Java support in Geek Gadgets is still under development. Especially there is not much documentation available to the date of this writing. This is partially owed to the fast evolution of the Java language standard.

There are two important packages dealing with Java:

Please refer to the GG-java-FAQ for further informations. See section `Top' in The GG-java-FAQ.

7.2.5 ld

[Details under construction]

Starting from 2.5.8 release, ld behaviour over symbols has changed. Default is now to strip all symbols from generated executable ONLY if environment variable LDSTRIP is set (to whatever you want). Otherwise, '-s' flag will strip symbols, as usual. Also packing of uninitialized data will be done automatically if LDSHORTDATA is set (to whatever you want). Ld also knows about -chip and -fast keywords, gcc will soon handle them directly. Ld is using now flavours, which are generated depending on gcc flags:

Gcc option Flavor passed to ld -m68020 -fl libm020 -noixemul -fl libnix -resident -fl libb

Thus ld when searching for libraries, adds those flavours to the library search path, in alphabetical order. Normal search path is /gnu/lib, and if for example you want to compile using -m68020 -noixemul ld will look for libgcc.a in: /gnu/lib/libm020/libnix first, then it will reduce flavours, one by one, if it can't find required library in flavour's expanded path. This means that it will try to find libgcc.a in: /gnu/lib/libm020 and in /gnu/lib/. Because libgcc.a exists in /gnu/lib/libm020, ld will take this one.

There is as for now 8 possibilities:

Flavors Search path libb libm020 libnix 0 0 0 /gnu/lib/ normal 0 0 1 /gnu/lib/libnix/ non-ixemul 0 1 0 /gnu/lib/libm020/ normal 68020 0 1 1 /gnu/lib/libm020/libnix/ non-ixemul 68020 1 0 0 /gnu/lib/libb/ baserel 1 0 1 /gnu/lib/libb/libnix/ baserel non-ixemul 1 1 0 /gnu/lib/libb/libm020/ baserel 68020 1 1 1 /gnu/lib/libb/libm020/libnix/ baserel 68020 non-ix

Using this approach makes adding flavours pretty easy, if someone wants for example to add 68881 libraries, a new flavour will have to be created, libm881, and thus the maximum flavour search path level would be: /gnu/lib/libb/libm020/libm881/libnix, which can be translated to English as: "I want a base-relative library compiled using Motorola 68020 and coprocessor 68881, not using ixemul.library".

7.2.6 libnix

[Details under construction]

This is a standard link library to replace the functionality of ixemul.library. Make sure you link to it if you use the `-noixemul' command line option for gcc.

Libnix, a static (i.e. link) library for gcc 2.3.3 or above. It's not a replacement for ixemul.library (though it's possible to recompile most of the gcc environment with libnix) but a good thing for amiga specific development on gcc:

For an introduction and a comparison, see section 7.1.4 Ixemul vs. Libnix.

Please refer to the libnix documentation for further details. See section `Top' in The Libnix Manual.

7.2.7 X Windows

[Details under construction]

Geek Gadgets features a X Windows port called 'Xade'. Although already very stable it is still undergoing constant development, especially lacking documentation thereof.

Please refer to the ASCII documentation included with the X11 packages for now.

7.3 Advanced topics

This section summarizes informations concerning advanced topics. You should be aware that these may require a more indepth knowledge of programming in general, programming for AmigaOS or using the Geek Gadgets Developers Environment.

7.3.1 Linker Libraries

[Details under construction]

7.3.1.1 libamiga.a

[Details under construction]

Starting from 2.6.0 an Amiga OS compliant library (libamiga.a) is provided, thanks to libnix authors (Matthias Fleischer and Gunther Nikl).

Anyway if you want to rebuild one, there are two methods:

1) Using hunk2gcc; the AmigaDOS object converter made by Markus Wild. To achieve this, simply grab a copy of latest amiga.lib (from Commodore Development Kit) and make a new directory where you want your converted object files to go, cd into it, and enter

hunk2gcc amiga.lib [..further libs if you like..]

This generates an a.out object file for every program unit present in the hunk file (in this case, from amiga.lib).

As the final step convert all those files into an a.out style library by issuing:

ar qc libamiga.a obj.* ranlib libamiga.a

The ranlib run builds a symbol table in the archive, and makes accesses to the library much faster.

2) Creating a libamiga.a library with libnix is fairly easy, but takes some time. Just decompress sources.lha from libnix distribution and run a 'make libamiga.a'.

NOTE:

As long as you make no AmigaDOS specific calls, you can create a dummy library using:

cat "int dummy;" >dummy.c gcc -c dummy.c ar crv libamiga.a dummy.o mv libamiga.a gcc:lib

A small libamiga.a (dummy) is also provided with libnix.

Please be aware that the distributed libamiga.a exports several of its symbols, which means that you may end up with symbol name clashes or unexpected/undesired effects. For example, libamiga exports the array "color" in the Amiga custom chip address space, which clashes with a variable name color when compiling GNU chess.

7.3.1.2 libdebug.a

[Details under construction]

Since 2.7.2 an AmigaOS compatible libdebug.a is provided, thanks to Walter Harms.

@lowersections @lowersections


Go to the first, previous, next, last section, table of contents.