APDL Public Domain 1/APDL_PD1A.iso/program/c/gnu_c/getstarted/GetStarted

Text File | 1995-02-28 | 14.9 KB | 287 lines

Notes: GETTING STARTED  - Graham Seale  22-Oct-1994
Note 27-Feb 1995 This file now requires modification - lots has changed! - GS

THE BIG DUMMY'S GUIDE TO USING GCC 2.4.5 from A.P.D.L

What you really need to do to get !GCC to compile a real C sourcefile. This note
is for ABSOLUTE BEGINNERS, and anyone else, who (like me), are not among those
who can breeze through the "Manuals" in !GCC.Docs and have the whole lot up and
running in half an hour. This is my list of fixes to at least get it to run.
Then - if you like, you can embellish and augment the approach until you have a
complete whizz bang multitasking desktop development environment. This is
just stage 0.5 or something. When you are an expert, you can strip this note
down to be a model of brevity!.

Before we begin, be assured !GCC is INCREDIBLY GOOD VALUE. It outperforms the
Acorn, (and other) products I am told. Read ALL of this file before taking the plunge.
____________________________________________________________________________________

Be cautious about the MANUALS. The gcc, cpp and invoke documents assume you are
using UNIX or DOS conventions which allow the compiler to identify the type of
file by its extension. eg. <file>.c or <file>.h etc. Of course, this cannot work
in RiscOS. Instead , the subdirectory containing the file is to be "c." or "h."
or "s." or whatever. In my first experiences, it was not enough that the
sourcefile was in a directory called c. I got around it by using the -x option
to force the compiler to recognise the file as a C source. My  command line
includes the fragment
               "gcc -x c -<other options> etc".
____________________________________________________________________________________

Note the "manuals" texts are liberally sprinkled with control character text
meaningful only to a wordprocessor called "Tex" or "Texi". As it happens, the UNIX
based Tex text formatter is available free at nearly all points where GNU software can
be sourced. Very likely, like all GNU software, it could be ported to the Archimedes.
I have yet to explore a little further to find it. but it is an obvious thing to include
when distributing GCC - so we can read the manuals! Without Tex, it is just about
possible to disentangle text by selective deletion (misery!). THEN you need to
translate it into RiscOS-Speak (more misery!). This situation will change in time.
_____________________________________________________________________________________

1.0   The !GCC Files as supplied (from David Holden's A.P.D.L.) B194.

      <Shift> plus a double - click will  to reveal a directory containing the
files:

      !Boot
      !Run
      !Sprites
      !Help
      !Readme                and also the directories:

      bin
      gcc
      gpp
      UnixLib

      Then, from a second disc, you get:

      docs    -    a directory of documentation
      DrLink  -    a directory of linker files ...ESSENTIAL!
      RiscLib -    a directory stuffed with potentially useful stuff....CAUTION
      RiscOS  -    a directory of documentation about an earlier !GCC...CAUTION.

You don't need the RiscLib or RiscOS directories yet. They have their own
hazards, and come from an earlier version of GCC for Archimedes as tweaked into
life by Thomas Abey and friends in Germany. Don't chuck them out, there is good
stuff there. But for now, leave them strictly alone.

There may come a time when this file you are reading is also included among the
group - who knows. Anyway, to get things going, read on.
______________________________________________________________________________

1.1   Firstly, YOU NEED TO FIX THE !Boot and !Run FILES !!!!!!

      You will have noticed that as soon as you double - clicked !GCC, it simply
      opened up its directory window. The !Boot file will have previously set up
      variables called Run$Path, Unix$Path, GCC$Path and GPP$Path. This happens
      as soon as the !GCC directory and its !Boot file is seen by the Filer.

      When !GCC is double - clicked, the !Run file (among other things), runs
      the !Boot file all over again. This has the effect of repeatedly extending
      Run$Path with the same GCC$Path ad nausium. According to the book the
      correct way to prevent this happening is done thus:-

a)    In the !Boot file, find the line

      Set Run$Path <Run$Path>,<Obey$Dir>.bin.

      and then disable it either by turning it into a comment by inserting a
      | at the beginning of the line, or by deleting it altogether.

b)    Replace it with the line

      If "<GCC$Path>" = "" then Set Run$Path <Run$Path>,<Obey$Dir>.bin.

      This will ensure the pathname is appended once, and once only. If you want to
      invoke GCC from elsewhere (say from a RAMDISK), then you will have to ensure
      Run$Path gets extended to point there.

c)    In the !Run file, the line that re-runs the !Boot file seems unnecessary.
      I disabled that line, while accepting there may be situations when there
      is a need to restore the Filer_OpenDir, and UnixFS$/tmpvariables.
      Filer_OpenDir, and UnixFS$/tmp are set here.

      At this stage, simply typing gcc at the command line, or from a command
      script in an Obey file, will invoke the compiler, and provoke the message
      "no input files specified".

d)   Any compiler output appears in a window cut into the desktop screen, and
     freezes the desktop until you press <Space> or click the mouse to regain
     control, whence, the whole screen re-draws. If you  use the !ZAP editor
     from Dominic Symes, you have the nicer option of creating a "TaskExec" file
     (type FD6) to contain the line:-

        gcc -<options> -<more options> <sourcefile_path>.<sourcefile_name>

     The effect is to feed the compiler output into a !ZAP editor screen window.
     The text is much tidier if !ZAP was already on the iconbar.
____________________________________________________________________________________

1.2   WHERE TO PUT THE EXECUTABLES.

      The executables are all those APPs in the !GCC.bin directory. You can
      leave them just where they are. Once Run$Path has been set by the !Boot
      file the "gcc"command will find them. You COULD  move them to the main
      system library, where the path will always find them. I run a RiscPC600,
      and the executables proper home is ADFS::HardDisc4.$.!Boot.Library. Other
      machines no doubt have their equivalent. I chose to leave the C Apps in
      !GCC.bin, until I learned more about them. BE AWARE THERE IS ONE MORE
      EXECUTABLE CALLED "LINK" WHICH NEEDS TO BE PRESENT. More about this later.

___________________________________________________________________________________

 1.3  GCC NEEDS TO BE ABLE TO FIND THE SOURCE FILE.

       There is much given in the gcc and invoke documentation about "defaults"
       for where to find sources, headers, etc, all driven by the FILENAME
       EXTENSION. Since this concept does not apply in RiscOS, the !GCC.ReadMe
       file says:

       "GCC uses the same assumptions as norcroft CC, with C sources held in the
       '.c' subdirectory and header files held in the '.h' subdirectory, with
       C++ sources held in the '.cc' subdirectoy. By default, GCC will compile,
       assemble and link the supplied sources.
       For most of the details for using GCC see the file invoke_texi."

       In practice, (no doubt also in my ignorance), I have NOT found this to be
       the case. It seems that if the compiler is instructed to make object or
       assembler files without linking, it will create '.o' or '.s' sub -
       directories and put the output there. But it steadfastly refused to
       believe my C source was of the correct format until I forced the issue
       with a  -x c in the command. There is so much that the ReadMe file left
       unsaid. Catch22 is that you need to buy the Norcroft compiler to become
       familiar with "Norcroft assumptions", so that you can use !GCC. This is
       example of the yawning gap that newcomers face.

       The path to the SourceFile needs to be correct in the argument.
       for example:-

       gcc -<option> -<another_option> -<and_so_on> <path>.<c_source_textfile>
________________________________________________________________________________
    A TINY TESTBED OF OBEY FILES - HOW TO ISSUE THE COMMAND

a)    You COULD, if you liked, press F12 and go back to BBC- speak, setting
    paths, and driving it all from the command line. I cannot think of anything
    more objectionable, but some people would not have it any other way.
    Imagine typing out that command line every time.

b)    Slightly better, but hardly fun, is to stay in the desktop, but still drive
    the command line by selecting Task Window (^F12 or find it with a menu click
    under the green Acorn.

c)    You might be able to compose your C programs using a clever editor like
    Dominic Symes' !Zap. You can configure the thing to invoke the compiler from
    within the edit window using an appropriately set up function key macro. I might
    try this soon.

d)    You could use a combination of Obey and TaskObey files, as a simple way of setting
    up the process, and getting started. Look in the Example directory to find !Compile_C
    and  !Run_C. Use <shift><double click> and take a look at them. Note how the current
    directory is made to point at where the source is. Note that the Obey file called !Here
    (in the c directory) will do the same thing, if you want to issue the gcc command at
    the command line. !Here is not at all necessary if you had set the GCC  off by running
    !Compile_C. More on this in 2.3 .

    While it is compiling, a Task Window opens, showing the compiler output, error messages
    etc. and when done, a !RunImage file appears next to the source. Invoking the !RunImage
    by double clicking on it will cut a window into the desktop, and run within (fast).
    Using !Run_C opens a TaskWindow, and runs !RunImage within, (slower, but nicer).

e)    Note the source is nameed c_source, (it can be whatever temporary name takes your fancy,
    so long as it is the same as the name in the !Compile_C).

f)    The !Here file, placed in the same directory as the source, and double clicked , is
    just a cute way of setting the current directory to the same as the source.
    Then, you can avoid the long <path> in the command line. You can get away with just
    the source filename.  Clever clogs will set up environment variables (like C_Source$Path
    or something similar instead. Do all that later. There are more serious hurdles yet.

________________________________________________________________________________

2.1  YOU NEED A BIG CHUNK OF MEMORY!

     Either use the Task Manager to extend the allocation "Next" to about 2000K
     or use the statement WimpSlot -min 1800K -max 2400K.  I found 1200K was not
     enough, and 1432K was OK, as tried out on a trivial 4-line program.
     Without the memory allocated, various compiler stages will complain about
     being unable to create certain "/tmp" files, and later stages will complain
     about being unable to find and use them. The demand for memory goes in the
     command line obey (or TaskObey) file, NOT into !GCC boot or run files. This
     is a fine point on which my present knowledge founders, but it seems to work.
     I shall test the variants later.

     Apparently it is due to the structure of the "stack under UnixLib".
     and "GCC is unable to extend its wimpslot, therefore you will have to set it to
     the required size". The ReadMe file suggests 2 to 3 Meg

     I used and Obey file called c_setup to make a RAMDISK, copy the essential
     bits of !GCC into it, and set up a couple of directories inside exactly as in
     the example, with TaskObey files to run things. If you have enough memory, you
      can experience fast, silent compiling with no hard disc activity at all.
      There seems no perceptible advantage to this but it depends what you ask the
      program to do. Asking for a hard disc access in a 30,000 loop WILL slow you
      down a bit.

________________________________________________________________________________

2.2  YOU NEED A LINKER! (Read this bit carefully)

     A linker is not normally supplied with !GCC. Fortunately,the second
A.P.D.L. disc has DrLink on it. In the DrLink directory you should find:

DDE          -    A directory containing:
                               !DrLink
                                Readme

DrLink       -    An executable APP file <----  THIS IS THE ONE YOU NEED!
DrLink_doc   -    The largest documentation file.
Features     -    A crisp list of DrLink's abilities.

Copy the executable APP file called Drlink into !GCC.bin. Then, rename
the copy in !GCC.Bin to "link". (ie The APP is <path>.!GCC.bin.link ).

Advanced users can later get to grips with the DDE.!Drlink program (with
screwdriver and spanner icon). When you need to use the linker independently of
the compiler, this is where you might come. For now we just need to raid the main
APP from Drlink to give GCC a linking capability.

_______________________________________________________________________________

2.3   THE COMMAND LINE   -   (or COMMAND SCRIPT in Obey or TaskExec Files)

          The COMMAND LINE needs some special things in it as a norm.
 eg the -v switch, meaning "verbose - lets have lots of info back from the
compiler as to how things are going".

The -O option to "optimise" - recommended to reduce the amount of extra code.
Note that it is a capital "O".

The -S option will instruct to stop after compilation proper, but not to
continue into assembly or linking. It will create a text file of assembler
language and put it into a directory called "s", which it will create if it does
not already exist.  There are dozens of options to amuse and confuse you. The
command script I used to run a trivial program reads:-

             WimpSlot -min 1800K -max 2400K
             gcc -O -v -x c Trivial_C

The result is the creation of a !Runimage executable in the same directory as
your source. Double clicking it will run your program, or you can invoke it from
other command script files if you wish.

_________________________________________________________________________________
2.4

You may expect even a trivial program to generate about 30K of code. Quite a lot of
this will be system error messages, traps, checks, etc. which is the same for all the
programs, whatever their size.
___________________________________________________________________________________

It all seems very easy when you already know. For those experts who are now
about to fall about laughing, all the above was dug out the hard way, after many
attempts to winkle out the "cogniscienti" had failed. Either they were off to
better things, or did not care to impart their knowledge. Since not all of us cut
their teeth on a BBC model B, and worked up from there, this note is offered
in the hope it will help some who are like me.

                       **********  FIN  ***********