> net#arf:$.a500.RiscOS+.doc.ROM_apps

Author:  Neil Raine
Title:   RISC OS+ Applications in ROM
Status:  draft
History:
    24-Aug-89  NRaine  File created.
     7-Sep-89  NRaine  Stuff about !Chars and !Magnifier added.
    12-Sep-89  NRaine  Comment about !TinyDirs being the only application
                       removed.  Comments about configuration files and
                       internationalisation added.
    23-Feb-90  NRaine  Updated to deal with ResourceFS

Issues (this section will be removed in the final version)
------

BASIC 1.05 (24-Aug-89) is required to run the ROM-based applications, if the
Desktop module is in the RMA (the old one objects to PAGE being set inside
the RMA).


Overview
--------

The RISC OS+ desktop has a new icon called "Apps" on the iconbar.  When
clicked, a filer viewer containing the icons for the ROM applications is
displayed, and these can be double-clicked to run the applications.

The application icons represent application directories which live in a
special ROM filing system called "Resources:".  They each invoke the
application directly in ROM, thus saving a considerable amount of RAM space.

It is also possible to configure each of the applications to start up
automatically when the desktop starts, without requiring a boot file.


Structure
---------

A new module called ResourceFS implements the "Resources:" filing system,
and allows other modules to "register" files in this filing system (see
doc.ResourceFS for further details).

This allows each ROM application to be built as a single module, that
consists of the application itself, the resource files it requires, and a
small amount of code which deals with registering the resource files with
ResourceFS.  See the section "Building ROM applications" at the end of this
document for details of how these modules are built.

In addition, there is a "Resource Filer" module, which displays a directory
icon of "Resources:$.Apps" on the icon bar.  This is similar to a TinyDirs
directory, but uses the sprite "romapps" rather than "directory", and does
not allow the icon to be removed.  Clicking SELECT on the icon opens the
Apps directory, while the menu allows the auto-start options to be set or
"Resources:$" to be opened.

Thus the average punter will initially see a desktop which is the same as
before except for the "Apps" directory on the iconbar, which he can use to
get at the applications.


ResourceFS directory structure
------------------------------

The following directory structure is used:

        Resources:$.Apps.!<appnames>            ; the ROM applications
        Resources:$.Fonts                       ; the ROM fonts
        Resources:$.Resources.<modulenames>     ; the Desktop resources
        Resources:$.Resources.<appnames>        ; resources for the ROM apps

The relevant modules are:

        Module name             Language        Path variable (if any)
        -----------             --------        -------------
        !Alarm                  BASIC
        !Chars                  BASIC
        !Configure              C
        !Draw                   C
        !Edit                   C
        !FontCtrl               BASIC
        !Help                   BASIC
        !Magnifier              BASIC
        !Paint                  C
        !PrinterDM              BASIC
        ADFSFiler               Assembler       ADFSFiler$Path
        NetFiler                Assembler       NetFiler$Path
        Filer                   Assembler       Filer$Path
        FilerAct                C               FilerAct$Path
        FilerSWIs               C               FilerSWIs$Path
        Palette                 Assembler       Palette$Path
        RAMFSFiler              Assembler       RAMFSFiler$Path
        ResFiler                Assembler       ResFiler$Path
        Switcher                Assembler       Switcher$Path
        TinyDirs                Assembler       TinyDirs$Path
        Wimp                    Assembler       WindowManager$Path
        ROMFonts                Assembler       Font$Path


Path variables
--------------

The Fonts directory contains the ROM-based fonts, and are accessed by the
ROMFonts module setting up Font$Path as follows:

        *SetMacro Font$Path <Font$Prefix>.,Resources:$.Fonts.

(it only does this if Font$Path was previously set to "<Font$Prefix>.").

All the Desktop modules (ADFSFiler, NetFiler etc.) access their resource
files (Messages and Templates) via path variables, eg: "NetFiler:Messages". 
On initialisation, they check for the existence of the relevant path
variable and set up the appropriate default if it is not defined, eg:

        *Set NetFiler$Path Resources:$.Resources.NetFiler.

This allows the user to set up any or all of these path variables to point
to his own message files.

Note that the Wimp uses "WindowManager$Path" rather than "Wimp$Path", to
allow Wimp$Path to remain separate.  Its resources are:

        Resources:$.Resources.Wimp.Sprites
        Resources:$.Resources.Wimp.Sprites23
        Resources:$.Resources.Wimp.Templates

The Sprites files contain the Wimp's ROM sprite pool, and cannot be
redirected (since the Wimp needs direct access to their ROM addresses).


Auto-starting applications
--------------------------

The Apps directory contains the ROM applications, which each have a !foo
directory, and can be started up by "/Resources:$.Apps.!foo".  The Desktop
module will automatically start the applications using such commands, if the
corresponding bits in CMOS RAM are set, by issuing Wimp_StartTask as
appropriate.  It does this on *Desktop : after the normal modules have been
started, and before any parameters to the *Desktop command have been
decoded.

The CMOS RAM bytes 'DeskbootCMOS' (&D7) and 'Deskboot2CMOS' (&D8) are used
as follows:

   &D7: bit 0 set => auto-start   !Alarm
        bit 1 set => auto-tinydir !Chars
        bit 2 set => auto-start   !Configure
        bit 3 set => auto-start   !Draw
        bit 4 set => auto-start   !Edit
        bit 5 set => auto-tinydir !FontCtrl
        bit 6 set => auto-start   !Help
        bit 7 set => auto-start   !Magnifier
   &D8: bit 0 set => auto-start   !Paint
        bit 1 set => auto-start   !PrinterDM
        bit 2 set => auto-start   !TinyDirs
        bits 3..7 reserved

The default value of these bytes is 0,0 (ie. no applications are
auto-started).

Note that !Chars and !Magnifier are not auto-started, since they have no
iconbar icons of their own: instead they are put onto the iconbar using the
"*AddTinyDir" command.

Note that this auto-starting procedure does not occur if the *Desktop
command has a filename parameter, since in this case it is assumed that the
Desktop Boot file will start any applications that are required.  The
configuration options are provided to allow discless operation of the
machine.


Storing configuration data
--------------------------

The two applications "!Alarm" and "!PrinterDM" both need to store the user's
preferred settings somewhere.  Normally this is saved inside the application
directory, but clearly there are problems if this is in ROM.

The solution is that the actual !Alarm and !PrinterDM applications do not
contain the entire application, but simply the !Run files and the initial
configuration files.  The !Run file then sets up a path variable, consisting
of the current value of <Obey$Dir> (ie. the application directory itself)
and another directory in Resources:$ (eg. Resources:$.Resources.Alarm).

If an attempt is made to save configuration data into Resources:, the error
message "Copy !Alarm onto the application disc and run it from there"
results.  If the application is then copied onto disc and run from there,
alarms can be saved in the new application directory on the disc, while the
main body of the program is still located in the ROM.


Internationalisation
--------------------

Because !Alarm uses a path variable to access its resource files, it is
possible for the system administrator to put an updated copy of the
'Messages' file into the application directory on disc, and this will take
precedence over the version in the ROM directory, which is accessed via the
second path element.

Thus the messages file is not normally copied onto the disc when the user
copies !Alarm from the "Apps" directory, but can be included there if
required.

It is envisaged that an "internationalised" machine would include the whole
of the "Apps" directory on a disc (with new Message files), and the "Apps"
directory would be configured not to appear on the icon bar.

  [ Another way to internationalise the ROM would be to add a module that
    replaced the Message files in the Resources: filing system, by using the
    fact that files declared to ResourceFS will obscure those declared
    earlier with the same name.  However, this would require all the message
    files for the applications to be RAM-resident all the time.
  ]


Building ROM applications
-------------------------

The applications are built in one of three ways:

        Assembler programs:   run as modules
        C programs:           run as modules, with a special module wrapper
        BASIC programs:       set PAGE to an address in ROM, and RUN

Assembler programs:

    This is the simplest case.  There is only one instantiation of each
    module, which is started up by the Desktop module when the desktop is
    entered, using the Service_StartWimp protocol.

    These modules typically require a Messages file and a Templates file,
    which they create in Resources: using ResourceFS_RegisterFiles, and
    access via a path variable, to allow user-modification.

C programs:

    Using C release 3 and cmhg, it is possible to compile a C program to run
    as a module.  In addition, there is an extra piece of module wrapper
    which allows multiple copies of the same application to be started by
    means of a *command.  This *command is then invoked by the !Run file in
    Resources:$.Apps.!<app>.

    In the directory "net#arf:$.a500.AAsm164.make-a-mod" you will find the
    bits needed to make a C module that can also include its own resource
    files.  Note that you will need ObjAsm 1.64, which supports the "BIN"
    directive.

BASIC programs:

    The application directory in Resources:$.Apps.!<app> should only contain
    a !Run file, which sets up a path variable as follows:

        Set <app>$path <Obey$Dir>.,Resources:$.Resources.<app>.

    and then invokes "<app>:!RunLink".  This is a small BASIC program that
    opens the file "<app>:!RunImage", and then calls OS_FSControl (21) to
    read the filing system number and internal file handle of the file.  If
    the filing system number is 46 (ResourceFS), then it knows that the
    internal file handle is equal to the address of the file in ROM, so it
    sets PAGE to this value and then RUNs the main program directly in ROM. 
    Note that LOMEM is still set to application space, so the WimpSlot
    command in the !Run file should set up enough memory for the variables
    without the program body.

    In the directory "net#arf:$.a500.AAsm164.make-basic" you will find the
    bits needed to make a BASIC ROM application.

