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?), so
AmiUpdate needed 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 is two-fold, and it
involves the application writing a environment variable upon startup. This variable can then be checked, and the
installation location obtained. From there on, the system checks that location just like any other fixed location
(as in the OS components and libraries etc).
NOTE: With the release of "Update 1" of AmigaOS 4.1, this situation has changed somewhat. Because of the new
APPDIR: virtual device, programs that are assured to be running on Update 1 and not on previous versions can
now skip the setting of this variable because APPDIR: tracks the program location for you, and this system is
used internally by AmiUpdate. So as in the case of system components or third party additions that are always
installed to a fixed location, you can disregard the following instruction.
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"?
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 )
/* obtain the lock to the home directory */
if(( lock = IDOS->GetProgramDir() ))
TEXT varpath = "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,
/* 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.
Then what, how does it update?
The next step is then to notify the AmiUpdate system that your application is compatible, 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
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 has been
verified, all users will be able to take advantage of being able to download it.
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.
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.
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...
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 real power 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.
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.
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 it's destination, it also saves the old version into the Rollback system so that we may be able to restore the old version 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 Tunenet archive. This shows us a small difference in discovering the path that the application must be installed to.
; autoinstall for TuneNet
; : TunetNet AutoInstall 1.2 (7.1.2007)
; get the path to the executable from the ENV variable
Set TuneNet `GetEnv AppPaths/TuneNet`
; now copy everything in the archive (apart from the executable)
Copy tunenet/~(Tunenet) "$TuneNet" ALL CLONE QUIET
; copy and store a backup of the executable for Rollback
CopyStore tunenet/tunenet "$TuneNet"
; finally, free the variable
This time we are setting a local variable (called TuneNet) to the contents of the AppPaths/TuneNet variable, which is written by TuneNet itself each time it runs.
Now we have the location of TuneNets installation, we simply copy everything apart from the executable to the directory. The executable is copied via CopyStore,
and this again allows the RollBack system to access the old version which is being updated. 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.
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 (documentation etc) can be simply
copied which will not take up space in the Rollback system.