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