Latest News
29-12-2016
AmiUpdate V2.43 released.
3-10-2016
AmiUpdate V2.42 released.
30-10-2016
AmiUpdate V2.41 released.
25-4-2015
AmiUpdate V2.39 released.
25-4-2015
AmiUpdate V2.38 released.
8-1-2013
AmiUpdate V2.32
7-1-2013
AmiUpdate V2.31 released.
26-12-2012
AmiUpdate V2.27 released.
24-12-2012
AmiUpdate V2.26 released.
12-12-2012
AmiUpdate V2.25 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?), 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 )
    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.



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 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 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
UnSet TuneNet
						
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.



Last updated: 3-December-2016
Website design - Copyright © 2017 Simon Archer. AmiUpdate and its associated components - copyright © 2005-2017 Simon Archer
In program and website graphics - Copyright © 2005-2017 Robert Willie - Copyright © 2017 Martin Merz

Hosted by WebFusion