Compiling Angband (and Variants) for RISC OS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Document text by Musus Umbra, (c) 1999.   
Updates (c) 2004 by Antony Sidwell.

release 0.07 (2004-12-11)
describing front-end 1.30 (2004-03-06) and later.


Code by by Musus Umbra & Thomas Harris, with minor changes by Antony Sidwell
and some 32-bit cleanup by Harriet Bazley

What's new
``````````
        The frontend no longer supports RISC OS 2, and all binary parts are
        now 32-bit clean.  The tools and techniques are largely the same as in
        the previous release from 1999.


What is it?
```````````
        Basically, it's a couple of utilities and some information that
        should make it easier to maintain a port of an Angband variant.

        We initially created this to make our releases as good as they
        /should/ be (ie. no truncated filenames, nothing in the archive
        that shouldn't be, a solution to Sparkplug mangling filenames,
        etc) with as little effort as possible.

        The idea is that by providing these tools, and some basic
        guidelines on maintaining a RISC OS port of an Angband
        variant, other people using my front-end to port variants
        will follow our lead and provide similarly structured releases
        (avoiding some of the pitfalls we found on the way :)

        This information doesn't discuss the actual /porting/, just the
        maintenance of a port.  For information on using my front-end
        to compile a variant for RISC OS, see the documentation
        that came with it.

        Each of the little utilities has some minimal documentation
        in the Tools.Doc directory.


Prerequisites
`````````````
        The best archive tool to create release archives with is the
        InfoZip command line tool Zip.  Zip achieves significantly better
        compression than, say, Spark, ArcFS or PackDir and is very
        flexible.

        Zip can be downloaded from the InfoZip homepage, at:
        http://sunsite.doc.ic.ac.uk/packages/zip/

        The Zip tool should be somewhere on your Run$Path (eg. in your
        library directory).

        If you don't have Zip, or the source code is in a tarchive, etc.
        then despair not: the SrcMung program will do the donkey work
        of fixing extensions and line-endings for you (see later)


Variants and Vanilla
````````````````````
        The supplied files are for all variants, with only three
        exceptions (ie. these three files are the only ones in the template
        distribution you'll need to modify if you're compiling a variant)

        They are:

        !<Foo>band.!Variant
                This defines the name and filetype.  See later for more info.

        !<Foo>band.!Sprites
        !<Foo>band.!Sprites22
                You'll need to change all the sprites.  Load the
                supplied spritefile to see how some other variants
                have changed them.



Directory Structure
```````````````````
        To make the best use of these tools, you should keep each variant
        you are porting in a separate directory.  Just copy the supplied
        directory (from my source release archive) to a suitable place
        on your harddisc and give it a suitable name.

        The directory should contain (files marked with an Asterisk
        should have been supplied in the source release):

                !History  (*)
                        Documents work done on the front-end.

                        NB: If you make alterations to the front-end,
                        please contact me so that we can keep version
                        numbers/features in step, etc.

                !Read1st! (*)
                        Contains information on the auto-DeMunge function
                        and a reminder to read the other help files provided.

                !RelNotes (*)
                        Release notes specific to the port/variant.

                        Use this file to document any known problems, and
                        to inform users of significant changes between
                        (front-end) versions that might otherwise confuse
                        them (eg. when I changed the font handling).

                font-acn/prf (*)
                        A simple .prf file for mapping dungeon features
                        onto IBM character graphics.

                        The supplied .prf file is for Vanilla Angband.  If
                        the variant you are porting uses different/more
                        features then you will need to ammend this file
                        accordingly (see later).

                !<Foo>Band (ie. a renamed !Fooband from the archive)
                        The actual game application.  All the support
                        gubbins required are supplied with my front-end
                        code.  All you need to add is the lib and src
                        directories for the variant you're compiling.

                        You should edit the !Variant file to set the
                        characteristics of the variant - the !Run and
                        !Boot files shouldn't need altering at all.

                        The !Sprites(22) files should be edited to suit
                        your taste - try to follow the current convention
                        (ie. the variant initial(s) in the sprites and
                        if possible a distinctive colour scheme).  Some
                        sets are included in the distribution.

                        See later for notes on colouring, filetypes and
                        names.

                Any "ReadMe" files the game code was supplied with
                (they should, at the very least, be a ReadMe file.  If
                there isn't, use lib.file.news/txt as the ReadMe).

                Junk, and/or
                NotRelease
                        Any odds and sods you use that shouldn't be
                        included in the release archive (eg. savefiles
                        created during testing, etc).

                        The names "Junk" and "NotRelease" are important
                        since they are explicitly recognised by the
                        MkManifest utility (see later).


De-archiving the source
```````````````````````
        I recommend that where source is supplied in a zipfile you use
        unzip (the companion dearchiver to zip) to extract it, using the
        -aL options (which will force filenames to lowercase and correct
        the life-ending characters in the files for RISC OS).

        If you're dearchiving using unzip you may also like to set the
        system variable unzip$exts to "c:h:o" to get unzip to create
        a RISC OS style directory (ie. main.c will be extracted as
        c.main).

        (If you have to dearchive by some other means, there's a utility
        supplied (SrcMung) that will move things into the correct places
        and fix the line-end characters - see its own documentation for
        more info).

        Dearchive the source to a different directory to the one you're
        going to build the port/variant in.

        Copy/Move the game's source code into !<Foo>band.src (so the
        .c files are in !<Foo>band.src.c, etc).

        You can now follow the instructions in "Compiling" to get the
        Makefile and main-ros.c ready for compiling, unless they are
        already supplied and the latest frontend version.


The Lib directory
`````````````````
        The game's lib directory as supplied probably contains some stuff
        that you don't need/want.

        Lib.Xtra
                Anything in the lib.xtra directory is (almost certainly)
                useless for RISC OS.

                You should use the lib.xtra directory supplied with my
                source code as this contains the default fonts, etc.

        Lib.Data
                If the game supplies lib.data.*/raw files you should
                delete those and make it remake them from the
                lib.edit.*/txt files. They won't be included in the
                'manifest/txt' list (see later) anyway.

        Lib.User
                You should probably keep all the lib.user.*/prf files for
                other systems in your release (they give an idea of what's
                possible, etc) but it's no great shakes if you only keep
                the acorn specific ones

                NB: the files that don't mention a system are relevant to
                /all/ systems so you /must/ keep those.

                Check that the 'all system' files correctly include the
                Acorn specific ones (hopefully the format of these files
                should make it obvious how).

                You should use the pref-acn/prf file supplied with my
                source code rather than any that was supplied with the
                game.  This is because mine defines more macros than
                the original (which was for Kevin Bracey's port).


Colouring (the !Sprites files)
`````````
        There should be a spritefile supplied with my source code that
        contains several variant filetype (large) icons and the variant's
        own icon.

        It's probably best to make the sprites look their best in 256
        colour modes, but if possible they should also "work" in 16 colours.

        NB: don't use 256 colour sprites.


Names
`````
        There are two names you'll need for the !Variant obey file
        (quite apart from the ones in main-ros.c - see the main-ros.c
        documentation); they are:

        The name of the filetype
                This can be at most 8 characters, so you're probably
                going to have to abbreviate.

                Suitable names might be:
                        Angband PernBnd Zangband GSNband GWangbnd
                        etc.

        The name of the variant
                This is used to find game specific resources, etc. so
                must correspond with the various definitions in !!Variant.h.

                There is no specific limit on the length, but it may not
                include spaces or other "dodgy" characters, for example
                hyphens are *not* OK (Yin-Yangband uses "YinYangband"
                as the variant name).


Filetypes
`````````
        At the moment we're using some unofficial filetypes in a pretty
        slack way.  They're actually reserved for the user, so it's Bad
        of us to do this.  On the other hand, I don't think we'd manage
        to get a block of 30 or so filetypes allocated to Roguelike games,
        do you? :)

        For ease of reference, these are listed in a separate file
        "Filetypes" in this distribution.

        Note that the filetype isn't hard-coded into the game code anymore
        and should be set in the !Variant obey file.  This is how I decided
        to salve my conscience after using so many filetypes I shouldn't
        have...  (ie. if a user has a clash they can change the game's
        filetype very easily).



Compiling
`````````
        See the separate documentation of my front-end code for information
        on what needs altering, where and why.

        It used to be recommended that Squeeze or another binary squeezer
        was used on the executable (it saves a few hundred K), but as I
        don't have access to a 32-bit clean version of it, I can't do this
        myself.  If you do have such a thing, please consider adding the
        relevant section to the makefile so that you can use it.



MkManifest and the 'manifest/txt' file list
```````````````````````````````````````````
        There's quite a lot of stuff in the !<Foo>Band directory that you
        don't want to be distributing in your binary release.

        There's also quite a few filenames that get truncated to 10 characters
        when you copy the files onto a normal RISC OS filing system.  Some of
        these have specific extensions that need to be restored in order to
        make sure that the game works properly on systems that support long
        filenames (eg. NFS, RISC OS 4, etc).

        The way that I approached this was to create a textfile (called
        !<foo>band.manifest/txt) containing a list of all the files and
        directories that needed to be included in the binary release, then
        used that as input to zip.

        Obviously, this required a bit of effort to set up properly and was
        subject to the occasional gaff (eg. one of my Kamband binary releases
        was missing a crucial file because I forgot to include it in the file
        list...)

        Thomas decided that it might be easier to create the manifest/txt file
        automatically by scanning the actual game directory.  Between us
        we knocked up a program which does just this, and which has now
        become MkManifest.

        Almost everything that shouldn't be included in a binary release
        is catered for by MkManifest, and for all it uses a naive method
        to fix truncated file extensions it /should/ be fine for any
        Angband variant (and seems fine for all the ones we've ported, for
        instance).

        There may still be some things present in the manifest/txt list that
        shouldn't be, however (eg. Zangband 2.2.3c introduced alpha-test
        Python support and included some Python scripts in lib.script.  These
        scripts would be included by MkManifest, but shouldn't actually be
        distributed).  So do have a quick check that the manifest/txt file
        generated looks right.

        Use:
                By default, MkManifest works in the CSD, so change directory
                to the one containing your !<Foo>band, etc.

                Run MkManifest (double-click it). The manifest/txt file
                will be generated inside !<Foo>band.

                Note that the files included/excluded by MkManifest
                can easily be altered by ammending the program, if need be.


Manifest/txt
````````````
        Older versions of Sparkplug (pre 2.25 or so) can mangle filenames
        that contain dots when extracting them from archives.  Specifically,
        they extract foo.zip as foo_zip rather than the correct form, foo/zip.

        Also, if the game is installed on a filing system that only supports
        10 character filenames and then copied onto a filing system that
        supports longer filenames (eg. if a user has just installed RISC OS 4
        and reformatted their harddisc...) then it's very likely that the
        game will 'break' messily.

        To cope with this, the !Run file runs a program called "CheckBand"
        which tests for the presence of the "manifest/txt" file.  If the
        file is present but with a mangled filename then the entire
        manifest/txt file is parsed and all files whose names have been
        mangled are (hopefully!) restored to what they should be.

        Note that manifest/txt in conjunction with CheckBand effectively
        replace the older !DeMunge files generated by MkDemunge (and
        as such MkDemunge has been removed from this distribution).


Zipping it all up
`````````````````
        To use the manifest/txt file to create your release archive, make sure
        that the CSD is the directory containing your !Fooband application
        and then issue:

                *zip -u8 <archive_name> -@ <!Fooband.manifest/txt

        If you keep the release archive in the same directory
        as the game itself then make sure that the archive doesn't get
        accidentally included in the manifest/txt file...

        The -u causes Zip to update the archive (if it already exists) so
        only new (or changed) files will be added to it (or replaced in it).

        If you later alter manifest/txt for any reason, delete the release
        archive (if you bothered to keep it) to make sure that it is rebuilt
        properly.



Who's Who, and Contact details
``````````````````````````````

        Antony Sidwell (aka ajps)
        `````````````````````````
                Maintainer of this frontend package, creator of Mr.Att.

                Currently maintaining ports of:
                        Angband, Animeband, EyAngband, Gumband, NPPAngband,
                        OAngband, Randomband, sCthAngband, Steamband, ToME,
                        UnAngband, Zangband.

                Work in progress / Future plans:
                        General front-end bugfixing, an application patcher
                        to make it easier to distribute bugfixes to my
                        frequently buggy ports. :)

                Sundry notes:
                        Uses a 70+2Mb StrongARM RiscPC and either Acorn C/C++
                        or GCC for development.  Would welcome anyone taking
                        over maintenance of any the ports which take their
                        fancy (with the exception of Steamband, which I have
                        special affection for. :)  See your name in lights here!

                Net presence:
                        r.g.r.a lurker;  posts announcements as appropriate
                        but otherwise tends to lightly skim the group.
                        'ajps' on IRC.

                e-mail: antony@isparp.co.uk
                   web: http://ajps.mine.nu/
                        http://angband.isparp.co.uk/

        Musus Umbra (aka Adny)
        ``````````````````````
                Author of main-acn.c, this document, the game support
                stuff, etc.  The RISC OS port equivalent of Ben Harrison.

                No longer developing for RISC OS.

        Thomas Harris (aka Hotseat)
        ```````````````````````````
                Co-author of some of these tools, proof-reader extraordinaire,
                reporter of bugs, maintainer of the Angband Code, requester of
                features and all round good-bod.

                No longer developing for RISC OS.

