GEMini Atari/GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso/files/gnu/gccdocs/gccstart.txt

Text File | 1991-07-08 | 39.8 KB | 372 lines

@CB②PI⇧Fx0œF


            Mike Dorman's "Quick Start" docs for the GNU C compiler, GCC.F




               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
œF


          GNU C from GEM still need to read the next section on CLI-basedF


          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 <variable name> <variable value>




               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
œF


          to the path, just as GCCEXEC does.  I haven't bothered to findF


          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 <stdio.h>




               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
œF


          their processed information to the next link in the greatF


          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,
œF


          just as soon as Ian Lepore decides that they've been beta-testedF


          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.


œF


               The "-o" parameter (remember, this stuff is case-sensitive,F


          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
œF


          bunch of other files, an ugly process which is necessary toF


          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:




               [e-mail] 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.
P