[AppUtils

 AppUtils is a set of utilities written in BASIC to allow manipulation of applications in the Resources Apps directory.
]
[Display

 Use StrongED$Mode=Document for folded and coloured text in this manual. Remove the first character of every line to convert to plain text.
]
[Purpose

 Any of the pseudo-application folders added by *AddApp or included from the ROM Apps can be copied to a sub-directory in Apps.

 Any application can be added directly to a sub-directory in Apps.

 Any pseudo-application folder added by *AddApp can be removed and the RMA memory used recovered.

 All of the ROM apps can be killed and then initiated again, but only as a full set.
]
[Using

 Ensure the !AppUtils resource application has been 'seen'.

 This adds the utilities to the Run$Path, so that they can be called directly.

 As supplied the utilities are crunched, but the source is included.

 Alternatively double-click on the application, which will also open a directory of test files.
]
[Operation

 These utilities use my RFSFiles module.

 Each pseudo-application in the Apps directory that is added by *AddApp contains an Obey file to Run or Filer_Run each of the corresponding !Boot, !Help and !Run files in the original application, if they exist. These files are registered in Resources as a single block.

 The rom applications contain actual !Boot, !Help and !Run files. All the rom files in Resources are registered as a single block, but the application files are at the start of the block.

 *AppCopy uses SWI "RFS_Add" and is fairly straightforward. It copies any of an application's !Boot, !Help and !Run files that exist to the new directory in Apps.

 Other utilities require the address in memory of files in ResourceFS, which is provided by SWI "RFS_Data". An adjustment is required to account for the ResourceFS header to get the actual address of the Resource block.

 *AppRemove finds the first of !Boot, !Help or !Run files of a pseudo-application registered as one block by *AddApp. This block is de-registered and the memory released in the rma. There is a check that the command is not being used with the rom applications.

 *AppMove combines *AppCopy and *AppRemove with a check that it is not being used with the rom applications.

 *AppAddTo combines *AddApp with *AppMove, without the rom applications check, which should not be necessary.

 *AppsKill finds the !Boot file of !Alarm, which is the first of the very large block of files registered by the OS. It then finds the !Run file of !Paint, which is the last file of the ROM applications and immediately leads to the address of the main block of files. Both addresses are stored in system variables.

 The main files after the rom applications are registered, which duplicates them, then the whole block from !Alarm is de-registered, which removes the rom apps.

 *AppsInit reverses this, using the stored addresses.

 *AppsKill and *AppsInit are very much dependent on the way that the OS ROM is built, so they ought to be used with caution.
]
[Utilities

{AppCopy

 Copies a pseudo-application in the top level of the Resources Apps directory to a sub-directory.

.*AppCopy [-app] <appname> [-dir] <directory>

 appname	the name of the application
 directory	the name of the subdirectory to copy to

 The -app and -dir keywords are optional.

 The sub-directory can be deeper than one level, but there are limits to the total length of a filename.
}
{AppRemove

 Removes a pseudo-application in the top level of the Resources Apps directory.

.*AppRemove [-app] <appname>

 appname	the name of the application

 The -app keyword is optional.
}
{AppMove

 Copies a pseudo-application in the top level of the Resources Apps directory to a sub-directory and removes the original.

.*AppMove [-app] <appname> [-dir] <directory>

 appname	the name of the application
 directory	the name of the subdirectory to copy to

 The -app and -dir keywords are optional.

 The sub-directory can be deeper than one level, but there are limits to the total length of a filename.

 This cannot be used with the ROM apps.
}
{AppAddTo

 Add a pseudo-application to a sub-directory in the Resources Apps directory.

.*AppAddTo [-app] <pathname> [-dir] <directory>

 pathname	the full path name of the application to add
 directory	the name of the subdirectory to copy to

 The -app and -dir keywords are optional.

 The sub-directory can be deeper than one level, but there are limits to the total length of a filename.
}
{AppsKill

 Removes all the ROM applications in the top level of the Resources Apps directory.

.*AppsKill

 The ROM apps have to be removed all together.
}
{AppsInit

 Re-instates all the ROM applications in the top level of the Resources Apps directory.

.*AppsInit

 The ROM apps have to be reinstated all together.
}
]
[Errors

 Errors are reported in a single tasking error window.

{Syntax: *<command> <parameters>

 There is a mistake in the command parameters.
}
{*<command> cannot be used with ROM app <appname>

 *AppRemove and *AppMove cannot be used with the ROM apps.
}
{*<command> did not find <appname>

 *AppRemove *AppMove did not find an app to remove it.
}
{*<command> cannot remove <appname>

 *AppRemove or *AppMove cannot remove an app because it was not added with *AddApp.
}
{*AppAddTo did not add <pathname>

 *AppAddTo did not add an application because *AddApp failed to add it.
}
{*AppsKill has already been used

 The ROM apps have already been killed and cannot be killed again.
}
{*AppsKill does not work with this OS build

 The method for killing ROM apps does not work with this operating system build.
}
{*AppsInit cannot be used before apps are killed

 *AppsInit cannot be used before ROM apps have been killed.
}
]
[History

{0.23 03 Sep 2020

 The utilities are now included in an AppUtils module as *commands, using my Basilisk utility.

 The application loads this module and RFSFiles and the use remains identical, except that the utilities are no longer included on the Run$Path.
}
{0.22 17 Apr 2020

 An allocation has been approved.

 This is the first full release.
}
{0.21 02 Apr 2020

 The check for ROM apps names is now not case sensitive.

 In *AppRemove res$ was not changed to app$ on copying code.

 In *AppsKill the address of the main block is more quickly found from Apps.!Paint.!Run.
}
{0.20 31 Mar 2020

 Commands have been changed so that each starts *App.

 An Allocate application has been made.
}
{0.15 31 Mar 2020

 Error reports are now comprehensive.

 Removing an app does not rely on finding a !Boot file. *AddApp only adds Obey files for those of !Boot, !Help and !Run present in the source application.

 *KillRomApps and *InitRomApps now interact so that they cannot be called out of order or duplicated without an error.

 *KillRomApps has an elementary check for compatibility with the OS build.
}
{0.14 30 Mar 2020

 Removed the running of !Boot files in *CopyApp except for the ROM apps !Edit and !Draw.

 The end of the ROM apps in Resources is now found by inspection rather than relying on the address of Resources.BASIC.Messages. *KillRomApps still relies on Apps.!Alarm.!Boot being the first of all OS Resources files.

 There are some other small changes to the code for efficiency.
}
{0.13 29 Mar 2020

 Added *MoveApp to combine *CopyApp and *RemoveApp, but not for ROM apps.

 Added *AddAppTo to add an app directly to an Apps directory.
}
{0.12 29 Mar 2020

 A bug in the RFSFiles module triggers an error in later ARM processors that do not like unaligned loads.
}
{0.11 28 Mar 2020

 I forgot that my RFSFiles module has a single SWI to get ResourceFS addresses.

 This simplifies things and the utilities are even smaller, but the functionality remains the same.

 I also realised that the Alias$@ types would no longer be correct for the ROM apps, so *CopyApp now attempts to re-boot the applicaton in its new location. This is not fully tested.
}
{0.10 27 Mar 2020

. First Release

 It should be considered to be very much beta, and all comments are welcome.
}
]
