(c) 1990 S.Hawtin. Permission is granted to copy this file provided that: 1) It is not used for commercial gain 2) This notice is included in all copies 3) Altered copies are marked as such. No liability is accepted for the contents of the file. Welcome to NorthC, this is a public domain 'C' programming system, put together out of parts from people too numerous to mention. This disk contains all you require to start creating or porting 'C' programs on your Amiga. This file outlines the steps you should take to create a simple 'C' program, compile it and run it. This should work on anything from an unexpanded Amiga 500 upwards, however if you have an unexpanded Amiga 500 go out and buy a second drive, they don't cost much and they make your life so much easier. So, you have just got this new disk from the public domain, and you are wondering how to become a top 'C' wizard in an afternoon. Well you must start by writing a program. Lisp programmers always write factorial as their first program, but that is because they are strange. 'C' being a "real" language all 'C' programmers start with the "Hello World" program. This set of instructions assumes that the NorthC system is on a floppy called "NorthC:", if you are running on a hard disk, or a floppy called something else, you must make sure that the "NorthC:" device is set up by the script file "setup-NorthC". The steps you should take to produce your first program are as follows. 1) Backup Your Disk Write protect the original NorthC disk, so you can see through the hole, then either use the "Workbench"-"Duplicate" option, or the command "diskcopy" to make a copy of the NorthC floppy. Once you have done this always use the copy, that way if something goes wrong you still have the original. 2) Start the CLI As it currently stands you must run the 'C' compiler from the CLI, you must start up a CLI shell. Double click the shell icon in the "Workbench 1.3" floppy. 3) Set up the NorthC environment You will need to do this every time you run the 'C' compiler, once you get bored enough you could put this in the "s:startup-sequence" file. How you set up the environment depends on your configuration, there are three possibilities, either you have a hard disk, you have a second floppy, or you only have a single floppy. Edit the file "Setup-NorthC" on the "NorthC:" disk, run "memacs" from the "Extras 1.3" disk, select "Project"-"Visit File" then type "NorthC:Setup-NorthC". At the end of the file are three "execute" commands, comment out the two that do not apply, so if you are running on a single drive Amiga the end of the file should be execute NorthC:Single-disk ;execute NorthC:Dual-disk ;execute NorthC:Hard-disk with a ';' in front of the two lines that do not apply. 3a) A Single Floppy Type the CLI command execute NorthC:Setup-NorthC this will copy the necessary programs into the ram disk. Once you have compiled your first program I would suggest you use a slightly more complex way to run the system, see 8a below. 3b) If you have a second floppy drive Place the NorthC floppy into the second floppy drive, that is "df1:", and type cd NorthC: execute setup-NorthC this will add the "bin" directory to the search path and tell the system where to find the 'C' libraries. 3c) If you have a hard drive To run NorthC on a hard drive you need to copy the executables, the include files and the libraries on to your hard drive. Place the "NorthC:" disk into the floppy and type cd NorthC: execute setup-NorthC this will copy the executables to the "c:" directory, and create two new directories on "hd0:", if these directories are not suitable for your setup edit the "NorthC:Hard-Disk" file before running "Setup-NorthC". Once the files have been copied comment out all the "Hard-Disk" file except the final line. 4) Change Directory to the source directory The command cd NorthC:examples/hello should move you to a suitable empty source directory, this is where you will create the "Hello World" program. 5) Create a source file You should use "memacs" from the 1.3 Extras disk to enter a 'C' program, the command "Extras 1.3:tools/memacs" hello.c will start the editor up, enter the following file #include main() {/* The simplest 'C' program ever */ printf("\a\aHello World\n"); } once you have typed this in select "save-exit" on the "Project" menu, this will save the file to the disk and exit the program. You should learn to use "memacs" when typing 'C' programs, it is a version of the most widely used program editor for 'C' programmers. It has a large number of features that make it very powerful for editing programs. 6) Compile the file If you called your file "hello.c" type the command cc hello.c after much clunking of disk drives, and disk swapping if you have just the one drive, you will find that your directory contains a file "a.out" as well as "hello.c". Use the command list to show you the contents of the directory. 7) Run the file Once "a.out" has been created you can run the program by typing a.out you will be amazed by the result, or there again you might not be. Once you are bored with "a.out" remove it from the directory with the command delete #?.out 8) Create a Makefile "Real" 'C' programmers rarely us the "cc" command directly, they normally use a program called "make". Use "memacs" to create a file called "Makefile" containing hello : hello.o blink with $*.blink this tells "make" how to build the "hello" program. 8a) If you only have one floppy If you only have a single floppy system you will need to make some adjustments to your environment, edit the end of "setup-NorthC" to ;execute NorthC:Single-disk execute NorthC:Single-Make ;execute NorthC:Dual-disk ;execute NorthC:Hard-disk then at the end of every "Makefile" you create you should always type the lines # Single disk defines .c.o: NorthC:bin/NorthC $*.c NorthC:bin/A68K $*.s delete $*.s .asm.o: NorthC:bin/A68K $*.asm .s.o: NorthC:bin/A68K $*.s once you have updated the "setup-NorthC" file and the new "Makefile", reboot your machine, restart the CLI and retype execute NorthC:setup-NorthC you will now be able to use the rest of this example. 8b) For all machines Once you have created the "Makefile" we must create a file for the linker, use the command make $*.blink this will create a file called "hello.blink", now type the command make once again, after some delay, the command will stop. Use the "list" command to look at the directory, it should now contain "hello.o" and "hello". Try the command hello for some astounding results. The file "hello.o" is an "object" file, I will explain what they are for later. It is good practice to always use the "make" program when compiling your 'C' programs, if you want to know why read "make.doc". 9) Go again Edit the "hello.c" file to do something else, get ideas from published 'C' programs, public domain programs, friends, and anywhere else you can. There are a number of example programs on this disk look in the "examples" directory and the "tools" directory, steal all the good ideas from them (if you can find any). 10) Get serious Buy yourself a copy of "Kernigan & Ritchie" or better yet get someone else to buy one for you. I know it is expensive but if you get seriously into 'C' you will get your own copy in the end anyway. It really is the best book on 'C' ever written, even if the code layout is a bit weird. Find a good book for AmigaDOS, I cannot recommend any book here as I have yet to find one that doesn't require a degree in computer science to understand, however I am sure that some easy to understand books are around. Read the "libc.doc" file on this disk to see what is currently implemented in the NorthC library, read the "Bugs.doc" file especially if a program does something you really didn't expect, or if it fails to compile. 11) Multiple files As a taster for the complexities of programming I will explain about compiling large programs that are split over many files, ignore this bit if you want. Once you have a decent sized program you will want to split it over many source files, suppose you have a program that is written in the files "foo.c" "bar.c" and "baz.asm". You can compile the files with the command cc -ofoo foo.c bar.c baz.asm however this will recompile all three files each time you compile the program. The 'C' world contains four different types of file, source files, assembler files, object files and executable files. You can usually tell which category any file comes in by its extension, for example source file names end in ".c", for example "foo.c" "this.is.source.c" and so on. Object files normally end in ".o", assembler files end in ".s" or ".asm", and executable files have no extensions. The 'C' compilation process contains three stages, first a compiler that translates source files into assembler files, then an assembler that translates assembler files into object files, and finally a linker that combines a number of object files to create an executable. The "make" and "cc" commands will call each of these stages for you, when you type cc -ohello hello.c "cc" will first call the compiler, called NorthC, to create a file "hello.s", next "cc" will call the assembler, called A68K, to create a file "hello.o", and finally it will call the linker, Blink, to make the executable "hello", once this is created it will delete the intermediate files "hello.s" and "hello.o". The "make" command tends to leave the object files in the directory. So when we make the program the files "foo.o" "bar.o" and "baz.o" stay around. Now if the user changes "baz.asm" make knows that it must reassemble "baz.asm" then link "foo.o" "bar.o" and "baz.o". It does not need to recompile "foo.c" and "bar.c". Once you have understood all that you should find a good 'C' book and look up libraries, not to be confused with Amiga libraries, this will get you nicely confused again. I hope that didn't confuse you. Examine the source code for "cc" in tools, this will show what "cc" can do, if you would rather that it did something differently change the file "cc.c" make a note of the fact you have changed it at the top of the file and recompile it. The original "cc.c" was hacked together in a single evening with just the UNIX "cc" manual for a spec, so I won't mind if you 'improve' it, provided you note what changes you have made at the top of the source. 12) Share and Enjoy (or Go Stick Your Head in a Pig) Once you understand 'C' you should share your knowledge, if you have an interesting program put it into the public domain or make it shareware, if you find learners in 'C' and AmigaDOS explain how to do things, always remember that you once knew nothing about computers, even if it was a long time ago. Most of all you should have fun with computers, unless of course you are a COBOL programmer. 13) After If, as the sun slowly sets, you realise that the astounding NorthC disk has turned you from a puny BASIC programmer into a towering 'C' wizard you should get a "scheme" interpreter, for example on Fish 149, and "The Structure and Interpretation of Computer Programs" by "Ableson & Sussman". This book is the best introduction to programming I have ever read, once you have completed it you will know more about programming than most professionals. By the way the factorial function in scheme is (define (factorial n) (if (= n 0) 1 (* n (factorial (- n 1)))))