the

project

A "use case" is a scenario that walks through an example of how a software system can be used. This shows how the system interfaces to the outside world and gives insight how the main parts of the system work together. They are often used as a lively specification of the system, form the base for architectural design and are sometimes used for testing.

The goal for these use cases is to cover 90% of the normal use. Repeating the same steps is avoided and exceptions are not handled. Only use cases that show interaction between modules are useful at this moment, use cases should have an added value for the design. The use cases presented here have been carefully chosen with these goals in mind.

The uses cases presented here are not just for specification. Some design is already mixed in. This is possible, because for A-A-P there does not need to be a list of requirements before the design starts.

When reading the use cases, keep in mind that these are just examples of normal use. Many variations will be possible. Handling exceptions is omitted here.

Index:
Actors
Install an application from an executable
install an application from sources
Update an installed application
Modify and test an application
Distribute modifications for an application
Make a new release of an application
Report and fix a problem
Create a new application with the GUI IDE

Actors

These are the currently identified actors:

installer

Someone who uses A-A-P to install and update software packages. He may do a few configuration settings, but does not change the code. He may want to report problems and request new features.

developer

Someone who uses A-A-P to create and/or change software packages. He may also want to distribute his changes.

releaser

Someone who decides which version of parts together make a release of a package. Usually this is one of the developers, but in a special role.

Install an application from an executable

• The installer downloads a recipe from the web site of an application.
• The installer starts the "recipe executive" with the command to install an application according to the recipe.
• The "recipe executive" reads the main recipe and inspects the local system. For this system the recipe specifies a self-installing executable to be used, with a list of sites where it can be found. The "recipe executive" downloads the executable from one of the sites.
• The "recipe executive" runs the downloaded self-installing executable and finishes.

Install an application from sources

• The installer uses a web browser to search the A-A-P recipe store for the main recipe of an application. He downloads the recipe of choice and writes it in a temp file.
• The installer starts the "recipe executive" with the command to install an application according to the main recipe.
• The "recipe executive" reads the main recipe and inspects the local system. For this system the recipe specifies a secondary recipe to be used, with a list of sites where it can be found. The "recipe executive" downloads the secondary recipe from one of the sites.
• The "recipe executive" reads the secondary recipe. It specifies an archive to be downloaded and a list of patches to be applied. The "recipe executive" uses the list of main sites, as specified in the main recipe, to locate and download the archive. It uses the list of patch sites, as specified in the secondary recipe, to locale and download the patches.
• The "recipe executive" executes the rules in the secondary recipe to unpack the archive and apply the patches. Information about the applied patches is passed on to the "personal version control". Then it runs the specified configure script to show the installer the configuration options. Default values from the installer preferences are preselected.
• The installer selects some of the configuration options and tells the "recipe executive" to continue. It starts the configure script with the selected options.
• The "recipe executive" checks that the configure script finished successfully and starts the make command, as specified by the secondary recipe.
• The "recipe executive" checks that the make command finished successfully and starts the OS-specific package builder, as specified by the secondary recipe.
• The "recipe executive" checks that the package building finished successfully and starts the OS-specific package install program, as specified by the secondary recipe. The package install program installs the package and registers it has been installed.
• The "recipe executive" cleans up temporary files and tells the installer the work was done.

Update an installed application

• The installer starts the "recipe executive" with the command to update an application according to the main recipe.
• The "recipe executive" reads the main recipe and finds a list of sites where this recipe can be found. The "recipe executive" gets the recipe from one of the sites, and then finds out it didn't change.
• The "recipe executive" inspects the local system. For this system the recipe specifies a secondary recipe to be used, with a list of sites where it can be found. The "recipe executive" downloads the secondary recipe from one of the sites. (This is equal to installing an application from scratch).
• The "recipe executive" reads the updated secondary recipe. It specifies an archive to be downloaded and a list of patches to be applied. The "recipe executive" sees that the archive and some of the patches have already been downloaded before. It only downloads the missing patches. It uses the list of patch sites, as specified in the secondary recipe.
• The "recipe executive" obtains information about the already applied patches from the "personal version control". It then applies the new patches on top of the already patched files and passes relevant information to the "personal version control". It then runs the specified configure script, using the same configure settings as the previous time. No user interaction is needed.
• The "recipe executive" checks that the configure script finished successfully and starts executing the build recipe that was included. It follows the dependencies in the recipe and compares the signatures of the previous build with the current signatures of the files. In source files changes in white space and comments are ignored. Only the files that have relevant changes are compiled.
• The "recipe executive" follows the rules in the recipe to install the application for personal use. The installer tries out the new version and runs a few tests.
• The installer decides the updated package works well and starts the "recipe executive" with the command to install the application on the system. The "recipe executive" follows the rules in the recipe to install the application. It first backups the old version of the application and then installs the new version.
• After using the updated version for a while, the installer decides the old version can be deleted. He starts the "recipe executive" with the command to remove the backups. The "recipe executive" deletes the backup files.

Modify and test an application

• The developer starts the "recipe executive" to build the cross reference database. The "recipe executive" follows the rules in the recipes and starts the "cross referencer" to create the database files. (alternative: the database files are downloaded instead of generated)
• The developer browses files and documentation of the application, using his favorite editor. The editor invokes the "cross referencer" to lookup files that contain a referenced symbol and to locate the symbols within the files.
• The developer modifies files with the editor. The "personal version control" module takes care of tracking the changes.
• The developer starts the "recipe executive" from his editor to build the application. The "recipe executive" first starts the "dependency checker" to update dependencies between files. It then follows the dependencies in the recipe and compares the signatures of the previous build with the current signatures of the files. In source files changes in white space and comments are ignored. Only the files that have relevant changes are compiled.
• There is an error in one of the files. The "recipe executive" finishes with an error code. It filters the errors from the invoked commands into a uniform format. The editor parses the uniform error messages and jumps to the first error location. The developer changes the file and repeats the previous two steps.
• The build succeeds and the developer tries out the results. The developer uses the "personal version control" module to mark the changed files as a new version.

Distribute modifications for an application

• The developer uses the "personal version control" module to create a patch that contains the differences between the original version and his marked new version.
• The developer uses his favorite editor to write a recipe. It contains rules to use the original recipe to build the application and apply the patch he just made before the actual building.
• The developer tries out the recipe and patch on his local system, like in the install an application from sources use case. However, the resulting application is deleted instead of installed.
• The developer uploads the patch to his web site. He adds this URL to the recipe. He then uploads the recipe to the A-A-P recipe store and adds a nice description of his work.

Make a new release of an application

• The releaser obtains the main recipe from the VCS with a VCS-specific command. The recipe describes the type and location of the VCS and which files to obtain from there. The releaser starts the "recipe executive" to get the files locally. The "recipe executive" invokes the "Version control wrapper" to do the actual work.
• The releaser tests building the application (the building is similar to what happens in the install an application from sources use case).
• The releaser obtains a patch from a developer and applies it. The "personal version control" keeps track of the changes. This is repeated for each patch. The releaser tests building the application, just like above.
• The releaser starts the "recipe executive" to install the application for personal use. The releaser tries out the new version and runs a few tests.
• The releaser decides the version is good. He invokes the "recipe executive" to check in the current version in the VCS. The "recipe executive" finds the type and location of the VCS in the recipe and invokes the "Version control wrapper" to do the actual work.
• The releaser announces that the new version is available, which triggers an installer to update the application, as described in the Update an installed application use case, except that the files are obtained from the VCS (works like the first point of this use case).

Report and fix a problem

• The installer notices a problem in a package he installed (as mentioned in the Install an application from an executable or install an application from sources use case). He invokes the "recipe executive" to report the problem.
• The "recipe executive" looks in the recipe of the application for rules how to report a problem. This is passed on to the "Issue tracker wrapper", which starts an editor on an e-mail message, with some of the fields already filled in (application name, version, type of system, name of user, etc). The installer fills in the fields and closes the editor. The "Issue tracker wrapper" sends the information to the address specified in the recipe.
• The issue tracking system registers the problem and forwards the information to the developer. He inspects the problem report and tries to reproduce the problem.
• The developer fixes the problem and creates a patch. See the Modify and test an application and Distribute modifications for an application use cases.
• The developer invokes the "recipe executive" to check in the patch in the VCS. The "recipe executive" reads the information in the recipe and uses the "Version control wrapper" to do the actual work. This results in a prompt for the developer to describe the fixed problem. He adds a reference to the problem report.
• The developer invokes the "recipe executive" to close the problem report. The "recipe executive" looks in the recipe and passes the work on to the "Issue tracker wrapper". The developer adds a reference to the new version in the problem report.

Create a new application with the GUI IDE

• The developer starts the "GUI IDE" (referred to as IDE below). He selects the menu for creating a new project. The IDE presents him with a dialog, in which the developer selects the type of project he wants to create. He selects the "C program with GTK GUI" alternative. He enters the name of the application which is to be build.
• The developer adds the source files to the project, using a file selection dialog in the IDE. The developer also adds an aap configuration script and a documentation file to the project.
• The developer tells the IDE to edit the recipe. The IDE writes a recipe with the list of source files, the configuration script and non-standard preferences that the developer uses. Then the IDE invokes the preferred editor on the recipe. The developer adds a build rule to generate documentation from the source files. He adds the resulting documentation file to the list of documentation files in the recipe.
• The developer gives the IDE the "build" command. The IDE invokes the "recipe executive" with the project recipe. The "recipe executive" reads the recipe and starts the "Automatic configurer", which generates a Python script from the aap configuration script. The "recipe executive" executes this Python script. Then it starts the "dependency checker", which generates a dependency file. Then the "recipe executive" follows the build rules to compile the application. It collects error messages, which are returned to the IDE.
• The "GUI IDE" starts the preferred editor, passing on the error messages. The editor parses the error messages and jumps to the first error location. The developer looks through the code and tells the editor to lookup the documentation for a function.
• The editor invokes the "cross referencer" to lookup this function. The "cross referencer" notices there is no database file yet, and invokes the "recipe executive" to create it. It then looks up the function name for documentation, and does not find it. It finds a reference to the GTK database in the recipe (added by the IDE, since this is a GTK project). It invokes the "recipe executive" to obtain this database file. The "cross referencer" finds a URL in the database and invokes the preferred web browser to view the documentation for the function.
• The developer fixes the error and tells the IDE to build again. This succeeds. The developer runs the resulting application and tries a few things. He notices a problem.
• The developer tells the IDE to run the application in the debugger. The IDE invokes the "recipe executive" to build the application for debugging.
• Then the IDE invokes a debugger and an editor for the application. The developer sets breakpoints with the editor and steps through the code with the debugger, while the editor displays the code. The developer fixes the problem and tells the IDE to build again. This succeeds.
• The developer tells the IDE which version control system (VCS) to use. The IDE adds this information to the recipe. He then tells the IDE to mark the current files as a new version and distribute it. The IDE invokes the "recipe executive" do the work. It first executes the rule to generate the documentation from source code. Then the "recipe executive" uses the "Version control wrapper" to check all the files into the VCS and marks this as a new release.