@CBPIFx03´F Mike Dorman's "Quick Start" docs for the GNU C compiler, GCC.3F So you want to be a rock and roll star...Sorry, a Byrds flashback, I apologize. So you want to use GNU C. GENERAL COMMENTS Well, although GCC is a *very* good compiler--and free, to boot--it could be called, rather charitably, "user-hostile." I'm writing this document in the hopes of de-mystifying the process of setting-up and using it. I won't make any warranty that this document will save your sanity, help you sleep better, promote world peace, or even not cause you to trash your hard disk, so don't come crying to me if any of this happens. That's the official disclaimer, so let's get down to business. The GNU C compiler is a wonderful thing, but it was written on and developed for users of Unix (which is a registered trademark of AT&T) and Unix variants, and so it doesn't necessarily mesh with your ST all that well. I'll try and show you how to set it up to work from a command-line-interface (from here on out, a "CLI") or from the desktop, but depending on your system resources, one or the other or both may be out of the question. SYSTEM REQUIREMENTS To begin with, you need *at least* 1MB of ram. That's not that stringent a requirement these days, at least not for semi- serious development, but 1MB is also only going to allow you to compile *really small* programs. You best bet is with 2MB or more of system ram--4MB is really neat, and you would probably have enough space to have a ramdisk present for temporary files (GNU C creates a *lot* of them). Next, you need a hard-disk. There's no way around it--the program that actually *compiles* code is ~600K, so that did away with nearly a whole floppy-disk's worth of space right there. If you don't have one, you ought to, you would really like it. Come back when you have one, because until you do, you're not going to be able to use GCC at all. GENERAL SETUP INFO Assuming you have the hardware required, you need to set up GCC. The first setup I'll mention is that for CLI users--I haven't used this in a while, so forgive any inaccuracies you may find--tell me about them, though, since I will spend some time updating this document, if necessary--I use GCC myself, and much of this information is strictly experience-based. If I'd had this document, I would have been doing programming *many* months before I actually started, because I wouldn't have had to spend so much time sussing out the system. People who intend to use 3´F GNU C from GEM still need to read the next section on CLI-based3F setup--there's some concepts discussed there that you still need to be familiar with. CLI SETUP There are a bunch of CLIs around there, but some of them are not acceptable to GCC--the biggest reason being that some (notably PCOMMAND) force the command lines to uppercase, and GCC uses lower-case parameters all the time. I can personally recommend GULAM, an excellent CLI with a MicroEmacs-based built- in editing facility, and MUPFEL, the excellent CLI included with GEMINI. Once you've got your CLI in place and set up to reflect some of your personal foibles, you need to start customizing it for GCC. The first thing you need to do here is find your CLI's equivalent of MS-DOS's AUTOEXEC.BAT. For GULAM this is the file GULAM.G. For MUPFEL, this is MUPFEL.MUP. Fire up your favorite editor, set to edit this file. You will need to set six environment variables. Most shells use the format: setenv The environment variables you will nedd to set are: GCCEXEC GCC_EXEC_PREFIX GNULIB GNUINC TEMP PATH GCCEXEC GCCEXEC is the environment variable which points to the executables of GNU C. This variable requires that you give the complete path to where the executables are store, and then append "gcc-" to that path. For my system-setup, you'd get: setenv GCCEXEC g:\gnubin\gcc- Modify the drive letter and the pathname as you see fit to make it conform to your system. This variable points to the executables so GCC.TTP, the "compiler driver," can find them. GCC_EXEC_PREFIX GCC_EXEC_PREFIX seems to be functionally equivalent to GCCEXEC. In fact, it also has to have that silly "gcc-" appended 3´F to the path, just as GCCEXEC does. I haven't bothered to find3F out if these two variables are redundant. For my system-setup you'd end up with: setenv GCC_EXEC_PREFIX g:\gnubin\gcc- GNULIB GNULIB is the environment variable that points to the object libraries that contain the compiled startup and execution code that GCC uses--for instance, the code that comprises the standard input/output functions in the module "stdio." It also points to the files gcrt0.o and crt0.o, the two files that contain the runtime startup code for every GNU C-compiled program. Don't let the tech talk confuse you--let's just say that these are *very* necessary files. In the GCC 1.40 release that I uploaded, all these files were in the file LIBOLB68.LZH. Without these files, you're up the creek, so go get them if you don't already have them. For my system-setup, you'd have the following: setenv GNULIB g:\gnulib Note that this variable doesn't have to have any of the silly postfixes that GCCEXEC and GCC_EXEC_PREFIX require. It *should not* end in a backslash ("\"). GNUINC This variable tells GNU C where to find the header files for the compiler. These files are the ".h" files that you often see refered to in the first lines of a program, like this: #include These header files contain useful definitions of constants your program may need to know (such as NULL), or prototypes for various functions (such as printf--these prototypes allow the C compiler to make sure that you aren't handing some bogus arguments to a function). They are *very* necessary, also. In fact, everything I discuss here is pretty important--this is the stuff I *know* you need--anything else, well, its omission hasn't bitten me yet. For my system-setup, GNUINC is defined like this: setenv GNUINC g:\gnuinc The syntax is the same as GNULIB, not requiring any of the funky little additions that GCCEXEC and GCC_EXEC_PREFIX do. TEMP As I said before, GCC produces *lots* of temporary files, so that the various peices of the compiler can communicate and pass 3´F their processed information to the next link in the great3F compiler-chain. GNU C *deperately* needs to be told where to put these temporary files--otherwise it'll probably attempt to stash them in places that don't exist on your system--or maybe you do have a /gnu/gcc/cross-compile/temp directory, and I don't know what I'm talking about. :^) If you have a ramdisk, this is probably the place to put your temporary files, as doing that will make GNU C *fly*. Unfortunately, that upgrade to 4MB is a ways away for me, and since I need most of my 2.5 MB for GNU C to work in, I have to send temporary files to my hard drive. For my system-setup, TEMP is set to: setenv TEMP g: Notably, you *cannot* have this variable end in a backslash and still expect GCC to function. If TEMP is set incorrectly, you'll get some interesting, but somewhat obscure, error messages when you try to compile. You might want to try it, just so you'll see them, so you can recognize them in the future, because this one variable will probably bite you more than any other. PATH This may be the most important environment variable of them all. Despite the existence of GCCEXEC and GCC_EXEC_PREFIX, GNU C still uses the old, reliable PATH variable to find some of its files. For my system-setup I have PATH set up this way: setenv PATH c:\;g:\gnubin There are some interesting things about PATH that you should know. First, GEM *really*, **really** wants your boot device to be the first entry in PATH, hence the "c:\" as my first entry. The second item is this--GEM uses PATH to help itself find resource (.rsc) files for GEM applications. If you set you path correctly, you can move *all* of your resource files to one directory--possibly eliminating some clutter. The last comment I'll make is a little more general--PATH, GNULIB and GNUINC can all point to more than one particular directory. All you have to do is separate the different directories with commas (",") or semicolons (";"). BE WARNED! In GULAM, and I think MUPFEL, semicolons are used to "stack" commands, so you will need to enclose any variables which include them in quotes. For example: setenv PATH "c:\;g:\gnubin" GEM SETUP You have probably taken the harder road for the nonce--with the right tools (which I should be able to upload to GEnie, RSN, 3´F just as soon as Ian Lepore decides that they've been beta-tested3F enough), programming from the desktop can be a breeze, but right now, it requires some special tools that aren't as user-friendly as the ones I'm using. First, you need some way to set environment variables. As the preceeding text (marked for CLI users, but you did read it, didn't you, like I recommended?) might indicate, environment variables are what GNU C lives and dies by. Unfortunately, though GEM will use environment variables, it doesn't give you an easy way to set them. NeoDesk, by Gribnif Software, supports them, and if you don't have that, there's an auto-folder program called ENVIRON (it should be on GEnie) which will set them as well. You need to get one of these programs, read the documentation and set the variables that I spent the last few pages describing, but in accordance with your setup, of course. BASIC COMPILING EXAMPLES Well, once you've gotten all those variables set, you're ready to start compiling stuff. If you're using a CLI, you'll need to type gcc (don't hit enter yet!), and then wait a minute while I attend to the GEM people. If you're using GEM, you need to double-click on GCC.TTP, so that it gives you a dialog box so you can input command line options. There are a bunch of command line options, all well- documented in the GCC ST documentation. By the time you need the others, though, you will probably know enough to figure them out for yourself (a cop out, I know, but it's late, and I promised myself that I'd write this before I went to bed). For the moment, I'll show you some of the simpler, but most important, ones. For example, let's say you have the file wombat.c, and you want to compile it. You would probably want to type the following command line in (omitting the gcc at the beginning if you're using the desktop): gcc -v -O -o wombat.ttp wombat.c The "-v" parameter specifies *verbose* mode. This means that gcc and all the compiler programs will indicate that they're running, and give you the version numbers, and such. This isn't necessary, but it's useful, just to watch the process involved. The "-O" parameter specifies *optimize* mode. In this mode, GCC will try to produce the smallest, fastest code it can. Again, this isn't essential, but it *is* useful. 3´F The "-o" parameter (remember, this stuff is case-sensitive,3F which means using GCC from the desktop with TOS 1.0 *will not* work) has an attachment--in this case, "wombat.ttp". This parameter tells GCC what the output file's name will be. It isn't necessary, but without it, GCC will produce a file named "a.out". While this will be a perfectly fine executable, since it doesn't end in .tos, .ttp or .prg, TOS won't know it's meant to be executable, and will, therefore, stare at you blankly if you try to run it. The last parameter, "wombat.c", tells GCC what file to compile. You can include a path, such as "d:\wombat\wombat.c" if you choose--this is most useful from GEM, since you may not have the source file in the same directory as GCC. All this, though, only shows you how to do text-based, non- GEM programs. Thos are fine for IBM users, but we've got a built-in GUI, so you'll probably want to write GEM programs before long. Compiling those requires more parameters, such as in the example: gcc -v -O -o wombat.prg wombat.c -lgem This command line differs from the first in two respects. First, the target file is named .prg, so it will run with GEM and mouse support and all that. The second difference is the "-lgem" parameter. This tells the compiler to link in the library with all the object files that support GEM calls--probably named "gem.olb." Actually, the parameter is "-l", with "gem" denoting the name of a compiler library--one of those pesky, huge, ".olb" files. Assuming that you'e got everything set up right, you should have a program on your hands. Run and enjoy! MORE ADVANCED COMPILING There's one other thing that you ought to know about. One of C's features is the ability to compile modules of programs separately, and then link those together. In this way, you can avoid having one *huge* ".c" file, by putting routines in other, smaller, ".c" files. To do this properly, there are two steps you have to go through. First, you have to compile the separate modules into ".o" files. You do this with the command line: gcc -c -v -O wombat.c In this example, the "-c" flag tells the compiler to just compile the file, not to link it--which mashes it in with a 3´F bunch of other files, an ugly process which is necessary to3F create an executable file. This command line *should* produce a file with the same name as the ".c" file, but an extension of ".o." Once you have done this procedure to all your smaller routines, you then need to tell the compiler to link them to your main program module. You use this command line for that: gcc -v -O -o wombat.prg wombat.c smut.o lewd.o -lgem This will automagically link the files "smut.o" and "lewd.o" (or whatever the names of the object files you created in the above example are) into the file wombat.prg. It will then link in any necessary files from the GEM library. Hopefully, these steps will produce your first modularly-coded C program. FINAL NOTES Well, I've listened to the same CD four times typing this. I hope there's not too many inaccuracies, typos, blatant lies or spelling mistakes, but I'm sure there will be--it's late and I'm sleepy. In the event that you find something unclear, confusing, too brief or outright wrong, please leave mail for me at any of these electronic addresses--I want to make this document easy to use, and helpful, to boot, and am willing to revise it if it doesn't start out that way: MDORMAN1@UA1VM.UA.EDU on the Internet. mike.dorman on BIX. M.DORMAN2 on GEnie. On BIX I am active in the atari.st conference, and messages left in the c.language topic will get to me, as will e-mail. On GEnie, messages left in the GNU C topic--I don't remember the CAT and TOP numbers--will get to me, as will e-mail. Please remember, though, that this isn't meant to be a tutorial on programming in C on the ST--better people than I have written entire books about that. This file, will, I hope, make it easier to use GNU C for this purpose, though. Mike. Typed between the hours of 11 pm July 3, 1991 and 1am July 4, 1991 on WordPerfect for the ST. All the spelling errors are the computer's fault. P2