the

     A-A-P logo     

project


 

Use cases

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

An actor is someone or something outside of A-A-P that is using A-A-P to accomplish a task. Note that a real person can be more than one actor. For example, a person developing a software package may at times be in the role of a normal user when he installs a package or tries out the result of his work.

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.
index

Install an application from an executable

This is done by an installer actor.
  • 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.
index

Install an application from sources

This is done by an installer actor.
  • 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.
index

Update an installed application

This is done by an installer actor. This assumes the application was installed from sources already, as in the "Install an application from sources" use case. Except that in this case A-A-P recipes are used for building instead of Makefiles. The intermediate files (object files) of the previous build have not been deleted.
  • 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.
index

Modify and test an application

This is done by a developer actor. This assumes the application was installed from sources already, as in the "Install an application from sources" use case. What kind of modifications are done here is not important. They could be a port of an application to a specific system, for example.
  • 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.
index

Distribute modifications for an application

This is done by a developer actor. He has created a modified version of an application and wants to make it available to the world.
  • 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.
index

Make a new release of an application

This is done by a releaser actor. When this use case starts the application is present in one version in a version control system (VCS), including a recipe. Note that the number of modifications applied here can be anything from very small to huge, it doesn't matter for the sequence of events.
index

Report and fix a problem

This is done by an installer and a developer actor.
index

Create a new application with the GUI IDE

This is done by a developer actor. This uses the "GUI IDE" module. It would work similarly in the "console 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.
index

 

 
  The A-A-P pages:
home
news
Zimbu award
documentation
     Recipe examples
     Aap manual
     Agide tutorial
     features
     presentations
download
     Aap version log
     Agide version log
     ported apps
     packages
maillists and chat
plan and tasks
     SourceForge pages
     Aap todo list
     Agide todo list
architecture
     use cases
     modules
     interfaces
     design decisions
tools overview
     script languages
     build tools
     Install tools
     issue tracking
     version control
     browse tools
     IDEs
     various tools



Zimbu!



KwMap.net - browse the Keyword Map of A-a-p.org
 
funded by:

NLnet
	 logo


Send comments on this page to Webmaster AT a-a-p.org.            Hosted by SourceForge Logo            Also known as www.Agide.org.