INCDIR & INCLUDE ================ Ever looked at a source listing and thought to yourself ' What the hell is that ? '. You were probably looking at the include list at the start of the program. INCLUDE files are developed to make life easier for the programmer, though they do tend to confuse the beginner. Why INCLUDE Files ? ------------------- As you are probably aware, there are numerous subroutine libraries available to Amiga programmers. Assosiated with these subroutines are a vast amount of constants and data structures. Now the good-old-guy's at Commodore decided to give all these a name so one new what the other was talking about ( well that's the idea anyway ). Not only that, but they decided to give them 'meaningful' names. As well as the libraries there was also all the hardware registers ( POKE for result if you used to own a Spectrum ! ). All these we also given names. Commodore now had to find some means of passing this information from within their own ranks on to the not so fortunate 'other programmers'. They decided on an option that was informative ( Ho ho ) as well as useful. Enter the INCLUDE files. What's in an INCLUDE File ? --------------------------- Well if you are so lazy that you have not bothered to look yet, or even worse are using a pirate copy of an assembler, mend your ways ! INCLUDE files contain line after line of data definition instructions with the odd macro thrown in for good measure. Consider the following situation: You are writing a program and want to use a subroutine from the graphics library to draw a line. You know the subroutine exsists, but where is it ? You are faced with two alternatives. The first is to move away from your beloved Amiga, dig out a book and flick to the Index. The Index is probably naff ( you've got an Abicus book ) so you start scanning the pages until you find what you require, where the subroutine is. The second alternative is to INCLUDE the relevant files at the start of your program and refer to the subroutine by name, which is Draw. Now being an intellegent person, I am sure you can see which is the easier. Also being an intellegent person you would like to know the catch. The catch is two-fold. First you must know the name of the subroutine, this is usualy quite easy. Next comes the 'Revenge-of-the-Commodore-PR-Man' , no programmer would be so cruel. Some of the definitions in an INCLUDE file require values defined in another INCLUDE file, so you must INCLUDE that one as well. It is possible that some of the definitions in that file require values defined in another INCLUDE file. Things are not as bad as I make them seem. A conservationist who worked for Commodore made an attempt to remedy the situation, thus saving an unknown number of Lemmings from throwing themselves off a cliff in frustration. Most INCLUDE files that require information from another INCLUDE file will load that file itself ( and that one will load the next, which loads the next, which ..... ). If you use INCLUDE files, be prepared for SLOW assemblies. This can be frustrating, but it does make your life easier in the end. The logic ' I don't use include files so anyone can assemble my code ' has one major flaw: it will be as readable as Chinese is to an Inca, who has never travelled. How Do I Use INCLUDE Files ? ---------------------------- Before you start using INCLUDE files, you should know a little about the Amiga libraries. You wont learn about these reading this ! Still, if you have been reading the Abicus book 'Amiga Machine Language' then you will have got a taste of libraries. You will also have learned how not to program, but that's just my opinion ( Abacus books set me back a good two months and I had programmed the 68000 before ). Consider the first example in the above mentioned book ( Page 105 ), ExevBase = 4 AllocMem = -$c6 ..... move.l #number,d0 move #mode,a6 move.l ExecBase,a6 jsr AllocMem(a6) move.l d0,address beq error ..... Firstly, let me show you the same example with my own comments. ExevBase = 4 ;Why bother, use INCLUDE files AllocMem = -$c6 ; " " " " ..... move.l #number,d0 ;not defined above with other equ's move #mode,a6 ;WHO EDITED THIS--ASSHOLE move.l ExecBase,a6 ;well they got this right jsr AllocMem(a6) ; and this move.l d0,address ; and this beq error ; and probably this ..... ;Open to discussion Now if you were going to use Devpacs INCLUDE files, the correct listing would be: number = $1000 ;An example showing 1000 bytes move.l #number,d0 ;d0=num of bytes to reserve move.l #MEMF_PUBLIC,d1 ;d1=type of memory CALLEXEC AllocMem ;Ask Exec for memory move.l d0,address ;store addr of mem block beq error ;branch if mem not available ...... Notice in the Devpac example that : 1/ The ExecBase and AllocMem defenitions are missing 2/ A new constant MEMF_PUBLIC has been introduced 3/ A new instruction, CALLEXEC, has been introduced Why are things simpler ? Because I missed out the most important line ( on purpose, I do not work for Abacus ! ): INCLUDE df0:include/exec/exec_lib.i and INCLUDE df0:include/exec/exec.i These two files contain all the common constants and library offsets all set out as a list of equates. It saves you from having to do it yourself. The example above is rather trivial as only one function is being called. If you were writing a program of any length you would probably be calling the library routines by the tens. Imagine typing all those equates in at the start of each listing. No need, just INCLUDE the relevant files where they are defined for you. If you look at the last two INCLUDE lines I gave: INCLUDE df0:include/exec/exec_lib.i and INCLUDE df0:include/exec/exec.i notice that both are in the include/exec directory. For this reason, HiSoft have provided another command, INCDIR. With this command you can specify the directory at the start of your INCLUDE list and do not have to type it in every time. So the above will become: INCDIR df0:include/exec/ INCLUDE exec_lib.i INCLUDE exec.i Well that should have given you an idea of what INCLUDE files are all about. I am not going to dwell on the subject as I am covering the individual libraries in a series on this disc. M.Meany.