|
www.riscos.com Technical Support: |
A boot application sets the machine up whenever the computer is reset, giving users and applications control over the start up, configuration and use of the desktop. It also works interactively when a user double clicks on its icon.
RISC OS 3.5's boot application is named !Boot. RISC OS 3.6 introduced a wider range of boot applications (eg !Boot for booting from disc, !ArmBoot and !ShareBoot for booting from a remote machine or server on a network). You can use boot applications to boot older machines.
A boot application provides:
This chapter details the facilities provided by boot applications for integrating applications into the desktop, and that will continue to be supported in the future. Unless otherwise stated, all such facilities are available from RISC OS 3.5 onwards.
Although a search through a boot application will doubtless reveal features that are not documented here, you must not use them if you wish your application to work under future versions of RISC OS.
The user interface is described in the RISC OS 3 User Guide.
Amongst other things, this chapter tells you ways you can add to the files in a boot application. When doing so you must be aware that you may not have write permission, especially if the boot application is on a remote file server. If you try to write to a boot application, and the write fails, your software should fail gracefully, giving a suitable error message.
The kernel determines which boot application to run depending on the configured Boot state, filing system, drive/file server, and so on. It then tries to find the boot application. If it fails, it saves the resultant error message in the system variable Boot$Error; if it succeeds, it runs the boot application.
Once a boot application has been found and run, it sets up a number of system variables as it first starts:
| Variable | Comments |
|---|---|
| Boot$Dir | The boot application's directory |
| Boot$OSVersion | The major version of RISC OS on the booting computer: for example '200', '310', '350', or '360' |
| Boot$Path | Comma separated list of boot application directory(s), each with a trailing '.' |
| Boot$State | The stage of booting: 'commands' or 'desktop' |
| Boot$ToBeLoaded | PreDesk directory (see The PreDesk directory) |
| Boot$ToBeTasks | Tasks directory (see The Tasks directory) |
| Boot$Unique | 'Local' if the boot file is local; a unique identifier for the machine if the boot file is remote |
(The RISC OS 3.5 !Boot application does not set the Boot$State and Boot$Unique variables.)
It then uses these variables to set up other variables giving the location(s) of Choices directory(s), which are used by applications - including the Boot application itself - to store start-up files, user preferences, and so on:
A boot application may have multiple Choices directories, and so store different choices for different machines, such as remote network stations. Each Choices directory can have the same structure beneath it, varied as required by the different machine(s) using each one.
RISC OS 3.6's network boot applications set the Choices$... variables to use the directory Boot:MchConfig.<Boot$Unique> out of preference, if it exists; failing that, to use Boot:Utils.RO<Boot$OSVersion>Hook if that exists, or otherwise to use Boot:Choices. Remote network stations will thus look for machine-specific choices; then either for RISC OS version-specific choices, or for system-wide choices. Network managers can hence use these different directories to support a mix of versions of RISC OS, and to provide machine-specific exceptions to the general setup.
For example, with the boot application Net::Server.$.!ArmBoot, these directories might be named:
You must not access the Choices directories by evaluating their full pathnames yourself, as the internal structure of boot applications is liable to change in future versions. You must instead use the methods described in the sections below.
The boot application then runs things before the desktop is entered. It uses two locations for this:
For full details, see the sections below.
The PreDesktop file contains the command line setup sequence. It gets invoked using Obey -c where possible, so that filing system or network software can be reloaded during its execution.
The PreDesktop file must always be accessed as:
This is to preserve future compatibility, should the structure of boot applications change.
The file has been divided into well defined sections for ease of maintenance, and to make it easy for scripts to install and remove application-specific entries. Each section starts with a header:
and ends with a footer:
As an example, the Aliases section supplied by !Boot in RISC OS 3.5 looks like this:
Scripts that scan the file should be extremely lax in what they accept. They should accept any amount of white space between each element (including before and after the '|' that introduces the header/footer), ignore case, and ignore the version numbers used by other applications.
When writing to the file scripts should use the exact syntax in the above example; see Adding to the file.
The sections supplied by a boot application are:
These are described in more detail below, starting with Comments.
Wherever possible, you should split anything you add into the same sections as above, each of which includes a header and footer. Each application should provide a script to install its sections. For each section, the script must:
So a finished file might look like this:
It is courteous to also supply a script to remove the entries.
The function of this section should be obvious!
This section sets aliases.
A boot application's section adds several aliases that you may find useful yourself:
The first alias set is for Alias itself, so that the following command:
sets the alias alias for the command command.
This makes the command Unalias to remove an alias:
The next alias gives a convenient way to set setting of paths:
so you can refer to a full pathname full_pathrest using the shorthand path:rest. For example:
would enable the following convenient commands:
PathMacro works similarly to Path, except the system variable set is a macro variable. For example:
To enable Thing: to be a reference to <Thing$Dir>.
This section is used to set standard paths and directories.
Run$Path is defined here to include the Library directory held within the boot application. This allows you to use the various commands held in the library, and defined in * Commands.
This section has been set aside for options that do not have any other place to be set.
This section uses the AddApp library command (see *AddApp) to register applications with ResourceFS for display in Resources:$.Apps.
A boot application's ResApps section registers all applications in Boot:^.Apps:
This section is used for any setup that does not obviously belong in any of the above sections. An example might be loading and binding a novel system beep.
The PreDesk directory must always be accessed as:
This is to preserve future compatibility, should the structure of boot applications change.
Your application !App may add a single file or subdirectory named App. You should only do so if the PreDesktop file does not meet your needs, since if too many applications use this directory, it may become full.
Your application may modify its own file(s) as it sees fit.
Under RISC OS 3.60, the files held within the PreDesk directory are acted on as follows:
All other files are loaded using *Load.
Then any directories are run; this searches for the file !Run in the directory, and runs it if found.
Under RISC OS 3.50, the files and directories held within the PreDesk directory are acted on in the following order:
The method for saving the desktop from the Task Manager remains the same as before, and is still the preferred way for applications to set themselves up and start. You should continue to use desktop saving provided it meets your needs.
If it does not meet your needs, you should read the sections below.
Earlier sections described how boot applications provide a file and a directory that are used to run things before the desktop is entered. They provide a similar file and directory that your application can use to start itself and/or any associated tasks:
You can add to this file as necessary, in the manner described below. If you only need to use a Desktop file, but cannot use the Task Manager's desktop boot file, then it is preferable to use this file rather than adding to the Tasks directory.
You should only add files here if your needs are met neither by the Task Manager's desktop boot file, nor by the Desktop file.
For full details, see the sections below.
The Desktop file must always be accessed as:
This is to preserve future compatibility, should the structure of boot applications change.
The file has the same format as the PreDesktop file. It is split into sections using headers and footers with the same syntax. See Format of the file.
The sections supplied by a boot application are:
The Auto tasks section is described in more detail below.
You should add sections to the Desktop file in just the same way as for the PreDesktop file. See Adding to the file.
Note that you should only add an Auto tasks section. There should be no Completion section in the file apart from that provided by the boot application itself.
This section boots all the system resources held in Boot:Resources:
This includes such things as !System, !Scrap and !Fonts.
It then runs all the files in the Tasks directory as Wimp tasks:
The Tasks directory must always be accessed as:
This is to preserve future compatibility, should the structure of boot applications change.
Your application !App may add a single file or subdirectory named App. You should only do so if the Desktop file does not meet your needs, since if too many applications use this directory, it may become full.
Your application may modify its own file(s) as it sees fit.
The files and directories held within the Tasks directory are run using Filer_Run.
Your application !App can create its own Choices directory, and use it to store user preferences.
Your application !App must always access its Choices directory as:
This is to preserve future compatibility, should the structure of boot applications change.
Your application !App may add any files or subdirectories it needs to. It may modify its own file(s) as it sees fit.
You should note that from RISC OS 3.6 onwards, the Boot application aliases the *Logon command to *SafeLogon, described on *SafeLogon. (Although this is not strictly a change to the *Logon command, most people will see it as such.)
In the unlikely event you need to force the use of the standard *Logon command, you must do so by using the '%' character to skip alias checking (see CLI effects), rather than by unsetting the variable Alias$Logon. This ensures that the change only applies to your command line, and does not alter the environment other programs expect to find.
A boot application uses various commands not provided by RISC OS 3.1 or earlier.
In RISC OS 3.5, these are provided by the boot application's Library subdirectory, which is added to the run path when the boot application is first run. In RISC OS 3.6 most of these are instead provided by a new module named BootCommands.
The advantage of the BootCommands module is that it avoids the need to load the commands over the network if a station is using a remote boot application. Booting is thus made faster.
Adds entries in Resources:$.Apps for all applications matching a wildcard pattern
*AddApp [directory.]pattern
pattern - wildcarded pattern to match
*AddApp adds entries in Resources:$.Apps for all applications matching the wildcard pattern in the given directory, or in the current directory if none is specified. If nothing matches the pattern, no error is generated; the command just returns.
You must not use this command to add applications that are already held in ResourceFS.
This command is provided either by the boot application's Library subdirectory (which is added to the run path when the boot application is first run), or by the BootCommands module added in RISC OS 3.6.
*AddApp ADFS::MHardy.$.MyApps.*
None
AppSize size[K]
size[K] - number of (kilo)bytes of memory desired for applications
*AppSize moves memory into or out of the RMA, attempting to move the difference between the current size of application workspace and the given desired size. In RISC OS 3.1 and earlier, the memory was transferred to/from the application workspace (hence the name of the command); from RISC OS 3.5 onwards, memory is transferred to/from the free pool.
This command is used at startup to shrink the RMA to its smallest possible size by setting the desired application size to a large value, and should not be used by other applications.
This command is provided either by the boot application's Library subdirectory (which is added to the run path when the boot application is first run), or by the BootCommands module added in RISC OS 3.6.
AppSize 514000K
Passes a command to XOS_GSTrans, and then passes it to the CLI
*Do command
*Do passes a command to XOS_GSTrans, and then passes it to the CLI.
It is useful when the command being invoked does not itself GSTrans its parameters, but you wish to pass parameters using GS string format (eg system variables). For more details, see GS string operations.
This command is provided either by the boot application's Library subdirectory (which is added to the run path when the boot application is first run), or by the BootCommands module added in RISC OS 3.6.
*Do BadCmd <Obey$Dir> - Expands Obey$Dir before calling BadCmd
None
FontMerge source [destination]
source - source directory of fonts to merge
destination - destination directory of fonts to merge
*FontMerge merges new fonts into an existing !Fonts directory. The first thing it does is to work out the destination for the merge.
If no destination is given, the third-from-last element of Font$Path is used. This may seem a bit strange, but consider what Font$Path will look like:
The last element is in the Resource filing system, which cannot be used as the destination. The next-to-last element is <Font$Prefix>; this is provided for backwards compatibility, so it is not a good idea to use it as the destination. The third-from-last element is therefore the one used.
*FontMerge can automatically create and use an overflow directory should the original destination become full. For a directory !Fonts, the overflow directories are !Fonts1, !Fonts2, and so on. *FontMerge checks for the presence of such overflow directories, and uses the highest numbered one as the initial destination.
Once *FontMerge has worked out the destination, it merges the fonts, creating overflow directories as necessary. It automatically processes font messages files, generating them for all languages given in the source and destination.
*FontMerge can be run from desktop applications. It initialises itself as a Wimp task to generate Wimp error boxes if it has an error; it calls Hourglass_Percentage as it does the merge.
This command is provided by the boot application's Library subdirectory (which is added to the run path when the boot application is first run). *FontMerge is a directory, and should be left as such. This is to enable *FontMerge to be localised for a particular country simply by replacing the messages file inside the FontMerge directory. Even though *FontMerge is a directory and not a file, you use it just like any other command line program.
*FontMerge ADFS::FontVendor.$.!Fonts
Checks for the presence of a given object, and executes one command if it exists, or another if it does not
*IfThere object_spec Then true_command [Else false_command]
object_spec - a valid (wildcarded) pathname specifying a file or directory
true_command - command to execute if object_spec is matched
false_command command to execute if object_spec is not matched
*IfThere checks for the presence of the given object, and executes the true command if it exists, or the optional false command if it does not.
The check is done using OS_File 17. Note that non-files (eg directories and partitions) will still cause the true command to execute.
This command is provided either by the boot application's Library subdirectory (which is added to the run path when the boot application is first run), or by the BootCommands module added in RISC OS 3.6.
*IfThere ADFS::MHardy.$.Run Then Delete ADFS::MHardy.$.Run
None
*LoadCMOS filename
filename - a valid pathname specifying a file
*LoadCMOS loads a file into the computer's CMOS RAM, preserving only the station number, the current year, and the DST flag. All other configured values are replaced by those stored in the file.
This command is used by boot applications to load a station's CMOS RAM at startup time, thus ensuring the machine is always in the same state. The boot application searches for the file:
and, if it finds the file, uses this command to load it. Note that the location of saved CMOS files is subject to change in future versions of boot applications.
This command is provided by the BootCommands module added in RISC OS 3.6. Unlike most other commands documented in this chapter, it is not a standard part of the RISC OS 3.5 boot application.
*LoadCMOS ADFS::MHardy.$.Safe.MyCMOS
Scans a given directory, applying a command to everything it finds
*Repeat command directory [-Directories] [-Applications] [-Files|-Type file_type] [-CommandTail cmdtail] [-Tasks]
command - command to apply to objects in the given directory
directory - a valid pathname specifying a directory
-Directories - apply the command only to directories
-Applications - apply the command only to applications
-Files - apply the command only to files
-Type - apply the command only to files of type file_type
file_type - a number (in hexadecimal by default) or text description of the file type to match. The command *Show File$Type* displays a list of valid file types.
-CommandTail - postfix the found object with cmdtail
cmdtail - command tail to apply to objects in the given directory
-Tasks - apply the command as a Wimp task
*Repeat scans the given directory applying a command to everything it finds, within the limits of the other parameters. The command executed is:
This utility does not recurse. Only those objects identified at the top level have the command applied to them.
This command is provided either by the boot application's Library subdirectory (which is added to the run path when the boot application is first run), or by the BootCommands module added in RISC OS 3.6.
The Library-based version uses the Scrap directory, and hence there must be some free space on the file system holding !Scrap for it to work. The BootCommands version does not have this limitation.
*Repeat Filer_Boot Boot:Resources -Applications -Tasks
Logs you on to a file server if you are not already logged on
*SafeLogon [[:]file_server_number|:file_server_name] user_name [[:Return]password]
file_server_number - the file server number to log on to
file_server_name - the file server name to log on to
user_name - as issued by the network manager
password - as set by the user
*SafeLogon logs you on to a file server if you are not already logged on.
The command first checks to see if the current temporary filing system is NetFS, and the given user is already logged on to the given file server; if so, the command exits immediately. Otherwise the command passes on a *Logon command to the current temporary filing system, leaving the command line tail unaltered.
This means that - unlike *Logon - *SafeLogon will not log you off a file server, and then immediately log you back on.
This command is provided by the BootCommands module added in RISC OS 3.6. Unlike most other commands documented in this chapter, it is not a standard part of the RISC OS 3.5 boot application.