RISC OS Build service

Introduction

JFPatch files can contain up to 8 distinct sections, of which 2 are required and must be present:

The required sections - the Header and the Code sections - are described first, below..

Example JFPatch files

Example usage, together with example API code, can be found in a supporting repository.

Header section

The header describes what the patch file is going to do. Entries are separated by one or more spaces, and are case insensitive:

If filenames are not full paths then the same path as the patch file is assumed, unless APP is specified, in which case, all references will be from that system variable (<name>$Dir).

Code section

Code lines are identified by a line outside DEFINE blocks which begins with a line starting with . (full stop), # or @.

Code sections may be prefixed by symbols as the first character on the line:

All lines which are not prefixed by these characters are checked for being predefined macros before being passed on to the basic assembler.

Labels

It is recommended that you use purely textual names for both routines and local labels (numerical initial characters are not allowed), ` prefixed names for variables - ie numbers or strings, and _ prefixed names for local labels which are local to a group of routines. eg .decimal, $`textstring, ._filename. This is merely a recommendation, and is not coded into the file format.

Local labels are defined as for normal labels, but instead of a . prefix, $ is used. To reference such labels within the code, use the same form (ie $variable name. These will be expanded during compilation.

Whilst compiling AOF code any lines with a | in are checked for exports or imports. Exports are achieved by using labels in the usual way:

will export the label label. To rename the label when exported you can use :

Label definitions in AOF may also be suffixed by ENTRY to indicate that they are to be declared as the entrypoint, in the form:

To refer to a label you can use either BL (or XBL) or one of the EQU commands:

Dependant on the EQU used, the correct import type should be selected. Calculations may be performed on labels, but you may NOT add labels together :

Predefined macros

These are used in much the same manner as standard instuctions, and may for the most part be considered as normal instructions. Where ## is given, the instruction may be given a conditional code:

Pre-assembler directives

Pre-assembler directives are prefixed by # and consist of a command followed by arguments:

boolean can be one of ON, TRUE, ENABLED, OFF, FALSE, DISABLED or =file to take the value from a particular file.

Conditional assembly

Conditional assembly allows you to cater for different possible configurations of the code so that it may be set up by the user to do different things.

Conditional assembly can take place in two forms. The first, default, form is for the pre-assembler to remove all non-required code, leaving just that which is required to be assembled. This is called external conditional assembly because the conditionals are evaluated externally to the code.

The second form is inline conditional assembly. This is where all the code is created in the BASIC file, and the conditionals are evaluated at assembly time. The external method is useful for debugging, whilst the inline method is more useful if the code has options which the user may select.

Conditionals in both forms are nestable, though you may become confused when trying to read such code:

The directives are:

Checking the validity of code

When you are writing patches, it is useful to perform check on the code you are acting on to ensure that it is the correct version. The checks are :

Including libraries of routines

Library files are used when it is rather pointless to code the same thing over and over again. They are held within the JFPatch directory in the file Libraries. The only library provided is the Strings library - a set of routines I have collected, modified and written (the string comparison routines are my own work, and though probably not optimal, suffice for the most part).

The syntax of the library inclusion command is :

filename is an absolute filename if there is a path, otherwise the JFPatch.Libraries directory is searched. routine may be * if you want all libraries to be included in a file - not recommended.

The # symbol means that the libraries will be included at this point in the code. Otherwise, a #HERE LIBRARIES directive will need to be issued.

The library files themselves consist of a first line which should be:

Followed by the routines in the library. Local labels may be used, but externally referenced variables may not due to the manner in which the inclusion occurs. Inclusion is from the first ; before the . prefix of the routine name to the line before the first ; before the next . (or the next . if there is no ;). See the Summary file for more details, and refer to Strings for examples. FIXME

Including code files

Just as library routines can be included in your code, so can files be included in the code. These can be used where you can't be bothered to code a section a number of times, but it is too specific for a full library.

The syntax of the include command is :

NOTE: This is still an experimental function. Please report problems or queries to Justin. (Note in 2020: He doesn't know how well this works)

Here directives (object location)

At some future point there may be more HERE directives to include pre-defined things (I'm not sure what yet, but in AOF there seems to be a lot of scope for that sort of thing...) Currently, however only two directives exist :

Pre-assembly section

The pre-assembly section is used to define constants to be used, and other various actions which occur to the programmer. Usually #CHECK and #COND set up directives are included here. The section is preceeded by PRE, and terminated by END PRE.

The only pre-assembler directives which make any sense are the #COND and #CHECK directives.

If you are assembling AOF code you may assign constants here by using the form :

Post-assembly section

This section is used for code which should be run after the code has been assembled. The section is enclosed by #Post and #End (or the end of the file). All the code given will be passed directly to Basic, unless it is prefixed by a # symbol. In which case, the following apply:

End section

All text in the end section will be appended to the file and never be executed, unless it is called as a PROCedure or FuNction.

This is useful for including information about the author, or program. However, it's real purpose is to allow functions to be used as macros.

Workspace

What is the point of using workspace blocks ? Well, it's easier to see a reference:

It is easier see that it means get the task handle from workspace than:

Begin a workspace block with DEFINE WORKSPACE and end it with END WORKSPACE. Within these blocks, you should use the following commands :

All other lines are treated in one of two ways. The first of these is the offset format, and the second is the relative format. Both give the same structure types, but the offset format gives the absolute offsets into the block. It is not recommended that you mix blocks.

Offset format

This can be used when you know all the offsets will be fixed, or if the lengths of the blocks are so awkward that you can't be bothered to do it by reference. In this form, the definitions are :

  offset  identifier[  comment]

where offset is either a decimal number, or a hex number prefixed by &.

Relative format

This is a much more powerful format for creating workspace structures, and is similar (though in no way compatible) to that used by ObjAsm. In this form, the definitions are :

  [=]variable  type[repetitions][  comment]

where type is :

     ^name[  repetitions]

repetitions is the number of times the space is repeated (ie four words would be !4).

Within this structure, blocks may be repeated, or "unioned" by using brackets to group the items. Placing a ( alone on a line begins a grouping, ) alone ends a grouping, and ) followed by a number sets a number repetitions for the block.

Within a grouping, | on its own on a line sets a union. This means that the relative pointer is reset to the start of that group so that an alternate set of names may be given. This is used in ObjAsm OSLib header files to define things like the Wimp_SendMessage blocks where the data is dependant on the code.

Such unions should be of equal length under the current version, or if not, the last union MUST be the largest. Later versions may remove this constraint, but should not be relied upon.

Using workspace

To use workspace within the code, use [ LDR|STR ][B]W or ADRW commands. To find the length of a block of workspace, use `len_name.

Module section

Modules are easy to write. You may not think that now, but after using JFPatch for some time to create modules, you will find that modules are so simple to program that you may have to get a life to fill the time you would have spent struggling... Only kidding people...

Module definitions are enclosed by DEFINE MODULE and END MODULE. Within these statements, the fields are:

The only one which really ought to be defined is NAME, although all are optional.

Init, final and service code

Whilst you may not have defined some of these, they may be created for you by JFPatch to implement other features. The cases are as follows :

Module workspace (private word)

Within each module there is a private word which is usually used to store the address of the modules workspace. Because of the way in JFPatch works (ie. creating it's own handlers), it is easier for these handlers to pass the address of the workspace to your routines, rather than a pointer to the workspace's address. This only applies if workspace is claimed; otherwise, r12 is a pointer to your private word just as normal.

If workspace is claimed, the following will have r12 pointing to the private space :

• Init
• Final
• Service
• Services (definition type)
• Events
• Vectors
• SWIs
• WimpSWIs
• Filters

Commands will NOT receive r12 -> workspace, but r12 -> private word, which contains the pointer to the workspace. Therefore, you should use

to get the pointer to the workspace. This is VERY important, otherwise you'll overwrite lots of very important pieces of data in the system heap.

Services

Services can be handled manually with the 'Service' entry, but a much easier way exists to do this by means of a definition block. Lines are in the form:

  service   code

Where service can be a decimal or hex number, or any string from the !JFPatch.Resources.Services file. This contains the service names (approximately) as given in OSLib header files. The block should be ended with:

  End Services

Vectors

Vectors can be claimed and released manually using init and final code, but by using a definition block many of the problems you may come across are removed and things look a bit clearer. The lines are of the form :

  vector   code

Where vector can be a decimal or hex number, or any string from the !JFPatch.Resources.Vectors file. This contains the vector names (approximately) as given in OSLib header files. The block should be ended with :

  End Vectors

Events

Whilst you can trap events using the Vectors call or manually, it's probably easier to have these in a seperate section. The lines are of the form :

  event   code

Where event is a decimal or hex number, or a string from the !JFPatch.Resources.Events file. This contains the vector names as given in OSLib headers files except that I've prepended the module name if there is one. The block should end with :

  End Events

Commands

Commands are denoted by COMMANDS to start, and END COMMANDS to end. Entries within this block, the fields are :

SYNTAX and HELP may be followed by a single line, or alternatively by .... In the latter form (three . characters), the next lines will be taken as being the message, terminating when the indentation reduce past that at the first line. To embed control strings, use GSTrans format.

Note again that r12 is not passed as the workspace, but as a pointer to the private word if the workspace is set.

SWIs

SWI blocks, like command blocks are surrounded by SWIs and END SWIs. Within this block, the following two fields are allowed:

All other lines should be in the form :

  number   alias   code

WimpSWIs

WimpSWIve is a gorgeous little module written by Andrew Clover which allows you to replace certain Wimp calls with other, much nicer calls :-) For more information, read the WSWI-Help documentation in Applics. Again, the section is surrounded by WIMPSWIS and END WIMPSWIS. And the fields are :

Either the Pre-Handler or the post handler may be prefixed by the ^ symbol. In which case, the code will have the high priority bit set. Mixed priority SWI handlers are not allowed, and you must use two seperate definitions if you wish to do that.

Filters

Filters are one of the most useful of the features of RO3 (to the programmer at least). Filters allow you to trap calls Wimp_Poll in much the same way that WimpSWIs do for the other calls. There are two types of Filters which can be used, Pre- and Post-poll filters. These are in seperate sections, delimited by opening and closing block statements. The filters which can be registered are:

• Pre-poll filter.
  Begin block with PREFILTER.
  End block with END PREFILTER or END FILTER.
• Post-poll filter.
  Begin block with POSTFILTER.
  End block with END POSTFILTER or END FILTER.
• Pre-rectangle redraw filter.
  Begin block with RECTFILTER.
  End block with END RECTFILTER or END FILTER.
• Post-rectangle redraw filter.
  Begin block with POSTRECTFILTER.
  End block with END POSTRECTFILTER or END FILTER.
• Copy rectangle region filter (not currently implemented).
• Post-icon redraw filter.
  Begin block with POSTICONFILTER.
  End block with END POSTICONFILTER or END FILTER.

The fields within each of the blocks are declared with the following definitions:

Post-filters must have either MASK or ACCEPT specified. ACCEPT commands must be given on seperate lines, and the names are :

Resources

Resources can be registered with ResourceFS when the module initialises by defining them in the Resources definition. The fields within the RESOURCES block take the form:

    local-filename    resourcefs-filename

Note: It is possible that the Resources registration is non-functional at present.

ImageFSs

The entry points and registrations for an ImageFS filesystem can be registered with the ImageFS block. The following fields are defined in the definition:

Full FSs

The entry points and registrations for a full filesystem can be registered with the FS block. The following fields are defined in the definition:

Note: The extra flags setting may be broken in the current implementation.

Macros section

The macros section declares macros - templated blocks of instructions - which are to be used within the assembly. The macros are not widely used and probably contain many bugs. The macro section is started with DEFINE MACROS and ended with END MACROS. The fields within the section are:

Macros are not well used within JFPatch code, so there will be bugs, and it may not work as described or as expected.