NB: This document is far from complete and, to say the least, far from
perfect.


(Re)compiling Angband (and variants) for RISC OS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Document text by Musus Umbra, (c) 1999
Updates (c) 2004 by Antony Sidwell.
                      
release 0.04 (2004-12-11)
describing front-end 1.30 (2004-03-06) and later.

What's new
``````````
        Various odds and ends, but nothing that changes compilation
        technique massively.


Introduction
````````````
        Okay, so you've decided to compile Angband (or one of its variants)
        for RISC OS - congratulations, you've passed the "good taste" test
        for both games and operating systems.

        This document describes how to customise my front-end source
        code to suit the variant that you are compiling.  It also
        explains how to use some of the additional niceties I added
        to improve the performance, etc. of some variants.

        There are some optional niceties which I nonetheless *strongly*
        recommend that you include.  These are clearly marked in this
        text :)

        Alongside this document there should have been some more general
        information on setting up your working directory and quite what
        is and isn't required to get a proper RISC OS *band compilation
        set up.

        There is also a copy of a usenet posting I made a few days ago, which
        I haven't yet incorporated into this document, and offers a brief
        description of the steps I take to compile a variant.


Prerequisites
`````````````
        Before we go any further you're going to need some stuff:

        1. The source code for the game you want to compile.

                If you don't have this, go and get it.  You might want
                to read the rest of this file first, just to see whether
                you're going to /want/ to compile it after all...

                ( Most variants' source code can be obtained from/via
                Thangorodrim: http://thangorodrim.angband.org/ ) 


        2. An ANSI C compiler.

                For example, Acorn's Desktop C (release 4 or 5 are both
                fine, but see later about release 5).

                GCC 3.4.4 (the current one at the time of writing) is
                also suitable.


        3. DeskLib 2.50 or later

                You can get this from the DeskLib home page:
                http://www.riscos.info/desklib

        4. Some sort of 'make' utility.

                Well, strictly speaking you don't /need/ this, but it is
                extremely helpful.

                The supplied makefile works with GNU make (which is supplied
                with the GCC distribution), and may work with recent versions
                of Norcroft make (amu) as it is supposed to support more
                GNUisms.


        5. A fair ole chunk o' memory

                If you're using GCC you'll need at least 6Mb free.  Acorn's
                C only needs 2 or 3 (IIRC) for most variants.  I tend to set
                the wimpslot to 15000k to give make and GCC space to work,
                these days.


        6. A fast machine and/or lots of patience

                It's going to take a while to compile, you see...
                It takes about 30mins to compile 'vanilla' Angband 2.8.3
                with no Borg on my machine using GCC, for instance.  The larger
                variants (eg. Zangband) can take a quite a bit longer.


Setting up
``````````
        You'll need to have set up the compiler you're going to use
        (obviously).

        You'll also need to set up the directory you're going to compile the
        game in.  Supplied with this file there should have been a !Angband
        directory - this contains the basic building blocks of an Angband
        (variant) using my front-end.



Setting up the application directory
````````````````````````````````````
        If you haven't already, now's the time to rename the !Angband from the
        release archive to suit the variant you're wanting to compile (eg.
        leave it alone for Angband, change it to, say, !Qangband for Qangband,
        etc).

        From now on, unless I say otherwise, I'll be talking about the contents
        of this !Angband directory (or whatever you've renamed it to).




Editing main-ros.c for variants
````````````````````````````````
        Hopefully all the differences between variants are taken care
        of in #defined constants at the top of main-ros.c.  For this reason
        there are a *lot* of #defined constants.  The advantage is that once
        you've got a set of working #defines for a variant you can use them
        every time.

        The constants all have explanatory text with the definitions so that
        you should be able to just dive in and see what happens.  Most of
        them are either cosmetic (variant name, author name, etc) or are
        responsible for getting certain function definitions to match those
        defined in the header files for the given variant.

        Due to my desire to reduce the work involved in making ports of new
        versions of variants, the "variations" directory in the distribution
        has a number of subdirectories containing a "Makefile/frag" for the
        given variant.  This has a variable called MR_SETTINGS which contains
        the values for the flags for that variant.  Eventually I might be
        able to construct a makefile to use these fragments for RISC OS.


File caching
````````````
        NB: This section may or may not still be true - the caching code has
        not been used for years, and most variants have changed a lot since
        then.


        You may define USE_FILECACHE if the game uses files of "random"
        lines (which most modern variants do) and you'd like them
        to be cached when first used (this makes a *huge* difference to Kamband
        1.4 and 1.5, for instance and a significant difference to Zangband).

        If you don't know what I'm talking about, check out Kamband or Zangband.
        (The presence of some text files other than news/txt and dead/txt in
        lib.file is a good indication that the variant is going to benefit
        from file caching).

        Note that if the variant you're compiling doesn't use such files
        then you should disable the file caching (ie. don't define
        USE_FILECACHE) as this will prevent unnecessary code from
        being compiled.

        If you define USE_FILECACHE you may also define:

                SMART_FILECACHE

                        If defined then the file cache will default to
                        'smart' mode, in which it automatically discards
                        blank lines and 'comments' (ie. lines beginning
                        with a # character).

                        This is provided mainly for the sake of Zangband
                        2.2.5 (and anything which draws on it).  Leave
                        this symbol undefined for other variants unless
                        you're sure it will work properly...

                        Note that the user may override this setting
                        with a command line option.


                ABBR_FILECACHE

                        If defined then the file cache routines will
                        attempt to compress the data as they cache it.
                        The compression method used isn't terribly efficient,
                        but it does make a difference and only requires a
                        very small amount of memory.

                        Because the compression can be a little slow
                        (especially since it normally needs an extra pass
                        through the source text in order to determine its
                        size when compressed) the cache will try to save
                        the compressed data to disc as a 'slave' file.

                        These 'slave' files are saved and loaded from
                        the normal 'scrap' location (which will be either
                        <Wimp$ScrapDir>.<Game> or from lib.xtra.rfcache if
                        <Wimp$ScrapDir> is not available for some reason).

                        If the game accessed lib.file.error/txt then
                        the cache would use <scrap_dir>.file.error/txt
                        as the 'slave' file.

                        NB: this compression will only work with 7-bit
                        ASCII text data.  The actual dictionaries used
                        are based on the contents of Zangband 2.2.5's
                        lib.file directory and so aren't particularly
                        wonderful for variants that use smaller and/or
                        substantially different files.

        If you intend to make use of the file-caching then you'll need to
        modify files.c to actually use the caching functions in the
        appropriate places.

        In order to facilitate this, the cache functions look identical
        to the normal file functions used to access the files.

        ie:
                cached_fopen()   replaces  my_fopen()
                cached_fclose()  replaces  my_fclose()
                cached_fgets()   replaces  my_fgets()

        Note that although the cached_* functions /apparently/ deal with
        FILE*s, they do NOT usually use real file handles.  This means
        that you *must* ensure that only cached_* functions are used
        for files opened with cached_fopen().

        The way that I typically deal with this is to simply move the
        game's random-line retrieval function(s) to the end of files.c
        and add the following above it/them:

              #define my_fopen(X,Y) cached_fopen(X,Y)
              #define my_fclose(X) cached_fclose(X)
              #define my_fgets(X,Y,Z) cached_fgets(X,Y,Z)
              extern FILE *cached_fopen( char *name, char *mode );
              extern errr cached_fclose( FILE *fch );
              extern errr cached_fgets( FILE *fch, char *buffer, int max_len );

        I recommend that you don't use SMART_FILECACHE or ABBR_FILECACHE unless
        you're sure that they are worth it.  Note that if you define the symbol
        FE_DEBUG_INFO when compiling main-acn.c a lump of debug code will be
        compiled in which will allow you to see how effective these options
        are (if they are enabled).


Panic Saves
```````````
        As of recent versions of my front-end, you can force the game to use a
        different filename when 'panic saving' due to crashes, etc.

        Specifically, if you replace two save_player() calls in files.c with
        save_player_panic_acn() the filename used for such saves will be
        !!PANIC!! in the same directory as the original savefile.  Make sure
        that you only replace the panic save calls and don't alter the 'death'
        save(s).

        I *strongly* recommend doing this as it can often mean the difference
        between a crash wiping out a character or not.



Check Modification Time
```````````````````````
        There is a check_modification_date() function defined in main-acn.c
        that can be used in place of the Unix one in init2.c for variants that
        have had this facility added.  NB: You'll need to #if out the relevant
        bits in init2.c.


Leftovers
`````````
        There are several bits of /my/ debugging code left in that there's a
        slim chance you might find useful.  To enable these, compile with
        FE_DEBUG_INFO defined.  This will compile some extra code to
        give you a 'Show debug info' option in the user (!) menu screen.

        This is probably most useful if you need to check what paths (for
        Lib, scrap, fonts and the like) are actually in use, and to check
        whether the current filecache settings are viable.


Command line Debugging flags
````````````````````````````
        As of front-end version 1.22 debugging flags may be passed on the
        command line using the -% flag (note that you should write -% as "-%%").

        At present there are two options available, both of which were
        previously controlled by defining symbols at compile time.

        The options are specified as a (decimal) number which is interpreted
        as a bitfield:

        bit 0 : ( previously "LOG_G_MALLOC" )

                Writes (on stderr) a log of all calls to ralloc() and rnfree()
                in the game's heap.  This only applies if using Dynamic Areas
                and only claims/releases from the game's heap are logged.

                If the game vanishes without a trace when using Dynamic Areas
                but is stable when not using them this can give you an
                indication of whether it is trying to rnfree() memory it
                claimed with malloc(), etc.

                [ Some Oangband versions, for instance, did this... ]


        bit 1 : ( previously "SHOW_SOUND_ALLOC" )

                Writes a file called "sndmap/out" in the game's Lib directory
                that lists the sounds allocated to specific events.  The file
                will also contain a report for any events in sound/cfg that
                weren't recognised.



Makefiles, bloody Makefiles
```````````````````````````
        Now it's time to put a makefile together (in case you don't know, a
        makefile describes how to "make" a program from its source files - the
        idea being that the computer can then be given the task of working out
        what needs doing and then doing it).

        Obviously, the makefile you need will depend on the variant you're
        compiling; I've supplied a couple of examples with this file.

        Basically, you need to compile and link all the .c files, all of which
        depend on all the .h files (in general).  The libraries you need to link
        against are the standard C library (stubs) and Desklib:o.Desklib.

        Makefile/ros is a GNU make makefile to build Vanilla Angband with either
        GCC or Norcroft.you should be able to adapt this to fit fairly easily,
        possibly using the variations.<variant>.Makefile/frag for guidance.

        Makefile/linux is the makefile I use to do crosscompiling with the
        GCCSDK, and mkvariant is a bash script which also helps a bit.

        [ More to be written on this... not really looking forward to
          describing how to set up makefiles... Also, GNU make's .SUFFIX rules
          seem to be broken so that makes things that bit more complex... ]


Problems...
```````````
        Vanilla Angband compiles with only about one warning (using Acorn's C)
        but the various variants tend to throw up a lot more (particularly with
        Acorn C).

        Obviously, I can't tell you what's wrong with the code the compiler is
        sulking about - you'll need to understand C syntax for that.


Compiler Bugs...
````````````````
        There is a compiler bug in Acorn (Norcroft) C/C++ release 5 which only
        appears to manifest when building 26-bit code rather than 32-bit clean.
        Should you be compiling like that (why?), you can uncomment some
        special-case targets in the Makefile (which is clearly commented) to
        alleviate the problem.  The affected files are usually monster2.c and
        object2.c.


Disclaimer, etc.
````````````````
        This file, and those with it, are supplied in good faith but without any
        warranty, express or implied, of any kind.

        The author cannot, and will not be held liable for any damage or loss
        arising from the use, misuse, or inability to use this
        information/software.

        Use at your own risk.

        Look both ways before crossing the road.


Contact
```````
I can be reached most easily be e-mail as antony@isparp.co.uk

I have a web-site at http://angband.isparp.co.uk/ which has an
Angband section containing the ports I've done.
