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:
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
|
