Latest News
31-10-2024
A new full archive of AmiUpdate V2.55 released.

11-10-2024
AmiUpdate V2.55 released.

21-2-2024
Update.library 53.20 released

18-2-2024
AmiUpdate V2.54 released.

16-2-2024
Updated the developer documentation and added more detailed coverage.

15-2-2024
The new Bugtracker is now online, thanks to MantisBT. Read more here.

12-2-2024
AmiUpdate V2.53 released.

This includes a fix to the Preferences editor and an application.library error.

Also spent some time giving the website some loving to ensure links etc now work due to the ongoing domain redirection problems.

10-2-2024
AmiUpdate V2.52 released.

Application support for developers

This section is dedicated to discussing how applications and components can take advantage of the AmiUpdate suite, and how you, as a developer, can adapt your applications.



On other systems, there is a central repository system that each and every application and component registers itself with, and this makes it easy to find out what has been installed on the host system. Unfortunately, AmigaOS does not have this facility (and lets be honest, would we really want to be tied down with such a mechanism? - ed), so AmiUpdate needs a way of detecting what applications and components had been installed and where. Without this, there would be no way to be able to inform the user that an update is available. The solution came with the release of "AmigaOS 4.1 Update 1", and consists of a virtual device called "APPDIR:" which tracks programs that have been used recently and stores their locations. This makes it very easy for us to find out where something has been installed to.

The following topics are discussed here:

So, how does it all work?



The first step is to notify the AmiUpdate system that your update is available, and this is done by adding or updating an entry in the database. In order to do this, the developer of the application needs to register for a user account. Once this account has been set up, the developer then has the ability to be able to modify or add entries to the database. You can register for an account from the login page, or click here.
Once logged in, you will notice a user menu appears which gives you various options, and the "My Applications" section is where you can edit your database entries. Once the update notification goes "live", all users will be able to take advantage of being able to download it.

Also: Because of the new APPDIR functionality in Update 1, you can take advantage of this by not specifying a path to your program when you add/edit the database entry. This will force AmiUpdate to check the system for your program, and this will also include via the APPDIR: device too.

back to the top





Automatic installation, how?



Some of the supported applications in the Contents section are able to automatically install themselves, and this is achieved by using a special script located in the root of the update archive. Let's use the CopyStore archive as an example. A listing of the archive is as follows:

AutoInstall 256 12-Feb-2007 CopyStore 24013 05-Aug-2007 CopyStore.doc 3255 05-Aug-2007 CopyStore_relnotes 2575 05-Aug-2007

This is the root of the archive once unpacked. The script we are interested in is called AutoInstall. This script is a standard DOS script which is executed once the archive has been downloaded and unpacked. Being a standard DOS script means that the developer can choose to take any number of actions in the script that they so choose. You may elect to do some simple copying, or even start an Installer script, but the real power comes from using the CopyStore command.
CopyStore gives you the facility to install your application as you would normally, but also allows a backup to be made that can be accessed by the RollBack system. This is where the versatility of the AmiUpdate suite comes into play, as in the event of an update which has caused problems, the RollBack tool can be used to "Undo" the installation.

back to the top





Tell me more about CopyStore...



Firstly, lets take a look at the AutoInstall script for CopyStore, this will hopefully help to explain the situation better:

; get the path to copy to GetEnv AUPath >NIL: ; copy CopyStore and create a RollBack opportunity CopyStore CopyStore "\$AUPath" ; copy the doc Copy CopyStore.doc "\$AUPath" CLONE QUIET ; copy the relnotes Copy CopyStore_relnotes "\$AUPath" CLONE QUIET



The first task is to get the path to install the update to, and this is done by GetEnv. The AUPath variable is located in ENV(ARC): and is written by AmiUpdate itself, so it always points to the location on disk where it is installed. This variable is also used to update not only CopyStore, but also AmiUpdate and the RollBack tool. Obviously, this only applies to AmiUpdate and its components. Normal application developers would need other ways to determine the location to install to.
Once we have the path, the CopyStore command is used to copy the executable to the location received from the variable. While this copies the new version to its destination, it also saves the old version into the Rollback system so that we may be able to restore it if needed. The rest of the script uses the standard AmigaDOS Copy command to install the document and release notes, which obviously are not saved into the Rollback system.


Let us consider another example, this time from the "ShowFiles" archive. This shows us a small difference in discovering the path that the application must be installed to.

; ShowFiles (SF) AutoInstall ; $VER: ShowFiles AutoInstall 0.930 (23.01.2018) ; Get the path to the executable from the ENV variable Set ShowFiles `GetEnv AppDir/ShowFiles` CopyStore ShowFiles/ShowFiles "$ShowFiles" If Exists "$ShowFiles/SF" Delete "$ShowFiles/SF" EndIf MakeLink "$ShowFiles/SF" "$ShowFiles/ShowFiles" SOFT FORCE CopyStore ShowFiles/ShowFiles.doc "SYS:Documentation/C/" ; Free the variable UnSet ShowFiles RequestChoice TITLE "ShowFiles (sf)" BODY "ShowFiles (sf) was updated on your system." GADGETS "OK"



This time we are setting a local variable (called "ShowFiles") to the contents of the AppDir/ShowFiles variable, which is a feature found in AmigaOS 4.1 and later. The virtual APPDIR: device tracks the location of programs that have been recently run and stores that location. This is how the script is able to determine the directory that files can be found and should be installed to.

Now we have the location of the ShowFiles installation, the executable is copied via CopyStore, and this again allows the RollBack system to access the old version which is being updated. In this example, the documentation is also installed using CopyStore. This is sometimes overkill, so consider the impact on disk space when deciding on just what to backup during the installation.

You may have noticed that the variable name has been quote-enclosed in the two example scripts listed above, and this is to protect against possible spaces in the location received from the environment variable. It is quite legal to have spaces in any part of the path that is stored in the variable, but once the script has expanded the variable contents, the spaces will produce unexpected results, and quotes around the variable name will allow us to use spaces without problems.

That is all you need to do in order to get your application or component not only AmiUpdate compatible, but also to get it to automatically install itself too.

back to the top





The host machine and install scripts



You may be releasing an update that is only applicable to one of a number of supported platforms, so you would need to know hat machine this update is being applied to:
In order to achieve this, the machine type is supplied as an argument to the AutoInstall script. The possible platforms are as follows:

  • BlizzardPPC
  • CyberstormPPC
  • AmigaOne
  • Sam440
  • Sam460
  • Pegasos2
  • X1000
  • X5020
  • X5040
  • A1220


This way the AutoInstall script can be made aware of the machine type by using the usual ".BRA" and ".KEY" pairing. Below is an example of how a script could install certain components depending on the host platform:

.KEY platform .BRA { .KET } echo "We can install common files here" if EQ {platform} BlizzardPPC echo "We can install Amiga A1200 specific files here" endif if EQ {platform} CyberstormPPC echo "We can install Amiga A4000 specific files here" endif if EQ {platform} AmigaOne echo "We can install Eyetech AmigaOne SE, XE and Micro specific files here" endif if EQ {platform} Sam440 echo "We can install ACube Sam440 EP and Flex specific files here" endif if EQ {platform} Sam460 echo "We can install ACube Sam460 specific files here" endif if EQ {platform} Pegasos2 echo "We can install BPlan Pegasos2 specific files here" endif if EQ {platform} X1000 echo "We can install AEON AmigaOne X1000 specific files here" endif if EQ {platform} X5020 echo "e can install AEON AmigaOne X5020 specific files here" endif if EQ {platform} X5040 echo "e can install AEON AmigaOne X5040 specific files here" endif echo "We can install common files here too, or do some post install type stuff, like renaming or removing files that apply to all platforms"


As we can see, the power of AutoInstall scripts is quite versatile, and allows adapting to a range of uses and situations.


Just a quick word on the usage of CopyStore.
As it creates a backup of the old version for possible later restoration, it is wise to consider disk space when choosing what to backup and what not to. As a general rule, only use CopyStore to install vital parts of the installation. Non-critical parts (icons, general texts etc) can be simply copied which will not take up space in the Rollback system.

back to the top





Supporting pre-Update 1 automatic installation



This section is now considered obsolete, and is only covered here for completeness. AmigaOS 4.1 Update 1 is the minimum version of the operating system supported. Prior versions are "End-of-Life", and no longer applicable.

Files that are always in the same place (libs: devs: Utilities etc) do not need to do any special setup before being run, as AmiUpdate can use a fixed location to search for it. This applies to any system extention installed in the SYS: disk, but if satellite programs (applications that use the library, for example) are to be installed anywhere the user chooses, then that application must comply with the following pre-start setup.



So, from a developers point of view, what is needed to be "AmiUpdate compatible"?

Please Note: The update to your application will not trigger until the second release with the compatibility code. The first release installs the setup required, but there is nothing to update yet, until the second release of the application that contains the code.

Give them options...

It might be worthy to note, that some users seem to be paranoid about software doing things "behind their backs", and filling up their drives with 'crap', as one user put it. So it might be an idea to make this compatibilty code an option via a preferences setting or tooltype. That way if a user doesn't want to halve their disk space, they can turn it off. Just an idea...

Well, as was mentioned earlier, the application or component needs to write an environment variable every time it starts up. One of the nice things with AmigaOS is the ability to be able to move things at will on disk without worrying about the installation being corrupted. By writing the variable each time the application is run, the contents of the variable is always correct, and thus the application may always be found, even when moved.
A very similar functionality was introduced with the recent release of AmigaOS 4.1 update 1, and the variable setting code has been modified to check for that. See below.


So, let's look at the steps needed for this:

Here is a function written in ANSI C which will write the variable for you. Thanks go to Colin Wenzel for this function (with slight alterations by me - ed!)

/********************************************************** ** ** The following function saves the variable name passed in ** 'varname' to the ENV(ARC) system so that the application ** can become AmiUpdate aware. ** **********************************************************/ void SetAmiUpdateENVVariable( char *varname ) { /* AmiUpdate support code */ /* if we are running on "Update 1", * skip the variable, we don't need it. */ if( ((struct Library *)ExecBase)->lib_Version >= 53 && ((struct Library *)ExecBase)->lib_Revision >= 12 ) return; BPTR lock; APTR oldwin; /* obtain the lock to the home directory */ if(( lock = IDOS->GetProgramDir() )) { TEXT progpath[2048]; TEXT varpath[1024] = "AppPaths"; /* get a unique name for the lock, this call uses device names, as there can be multiple volumes with the same name on the system */ if( IDOS->DevNameFromLock( lock, progpath, sizeof(progpath), DN_FULLPATH )) { /* stop any "Insert volume..." type requesters oldwin = IDOS->SetProcWindow((APTR)-1); /* finally set the variable to the path the executable was run from don't forget to supply the variable name to suit your application */ IDOS->AddPart( varpath, varname, 1024); IDOS->SetVar( varpath, progpath, -1, GVF_GLOBAL_ONLY|GVF_SAVE_VAR ); /* turn requesters back on */ IDOS->SetProcWindow( oldwin ); } } }

The function is well commented, so it should be fairly obvious what is happening. The function also stops DOS requesters during the write to allow for users that lock the system drive. Do not edit the function code, else there may be problems.
This function does make the assumption that "ExecBase" is defined as a global variable, and depending on the code, this may not be true. If you need to change the reference, please be carefull to ensure it is correct, or this function may return early under the wrong OS version.
To use the function from your own code, simply call it with the name of your application. As these variables are stored in one central directory, it is of paramount importance that each variable has a unique name. The easiest way to acheive this is to name it the same as your application. If you steal someone elses location variable, it could have serious consequences on the system during update time.
char *appname = "myapp";
SetAmiUpdateENVVariable( appname );
is all that is needed each time the application starts, so it needs to be in the main() function, preferably after all the library checks etc are done and the application is ready to start.




back to the top



Last updated: 08/12/2024
Website design - Copyright © 2024 Simon Archer. AmiUpdate and its associated components - copyright © 2005-2024 Simon Archer
In program and website graphics - Copyright © 2005-2024 Robert Willie - Copyright © 2024 Martin Merz

Hosted by TSOHost