Home
User
Overview
To create a package in IGUANA you need administrator rights in the CVS repository. If you have the rights, follow these steps:
Decide a location for the package
The first step is to decide a subsystem location for the new package. This depends on the function of the package. Use the following table to decide which subsystem to put your package into:
|
Ig_Data
Pure build- or run-time resource data such material definitions or pixmaps. No code here please.
|
|
Ig_Documentation
IGUANA documentation -- it goes all here.
|
|
Ig_Infrastructure
All packages that relate to our build and development infrastructure. Includes build scripts, documentation systems, quality assesment tools, etc.
|
|
Ig_Imports
All imported software as well as hacks to get non-imported external software to compile and link properly. However, do not put actual interface layers to external or imported software here. In general, if you import software here, do not modify it -- try to get the changes back to the original authors and get the modifications in the next release. If the external tools require special build configuration, change the package class in config/BuildFile and write a special makefile for it in config directory (if it is based on GNU autotools, please refer to the SoQt configuration). Also add a BuildFile to export the package features.
|
|
Ig_Extensions
Interfaces and adaptors for external software. In general these are mostly additional Qt widgets and utilities. Most packages belong in Ig_Modules, not here; add a new package here only after all IGUANA developers have formed a consensus on it.
|
|
Ig_Framework
Packages for IGUANA framework architecture. In general you should not add packages here; talk to Lassi if you feel your package belongs here.
|
|
Ig_Examples
Legacy example programs. Do not add new packages here. New example- or demo-programs should be plug-ins under Ig_Modules.
|
|
Ig_Applications
Applications go here. However, there shouldn't many new of those -- most new applications should be drivers and created under Ig_Modules.
|
|
Ig_Modules
Most new stuff should go here.
|
Create a new package in CVS
Edit the subsystem's .admin/NewLeaf. The "Valid Username" should be your CMS UNIX account name at CERN and recognised as a developer account on the CVS server. The "Valid Email" should be your e-mail address. The "New Leaf Name" should be the name of the package subdirectory, such as IgFoo, without the leading subsystem name.
All IGUANA packages and classes must begin with the prefix"Ig". Words in the name must have first letter capitalised, and then combined together (no intervening slashes or underscores). The only packages exempt from this convention are the imported packages under Ig_Imports. Please refer to the conventions document for more details.
Check in the .admin/NewLeaf with an empty message and ignore the check-in error. Usually you then want to rm .admin/NewLeaf and "cvs up .admin" so that your modified file won't get accidentally checked in again.
$ cvs ci -m '' .admin/NewLeaf $ rm -f .admin/NewLeaf $ cvs up .admin
Check the package out from CVS
Now check out the package. In the subsystem where you edited .admin/NewLeaf to add IgFoo now say:
$ cvs up IgFoo
Add a short package description
Go into the subdirectory created by the check out and edit the doc/html/index.html. Add a brief description of what this package is all about. The description will appear in the "Repository Structure" documentation generated automatically for each release.
Add the package into the build order
Now, add your package to the IGUANA build order -- otherwise it won't get built if you build the release from the top-level. Edit config/Project_makefile.mk and add your package in the appropriate location in the list. Note that since we link our libraries against their dependencies, you must add your package after all the packages you depend on.
Modify BuildFile
Finally, modify your BuildFile to cause your package to be linked against its dependencies and to provide its user packages the appropriate library.
Our convention is that every package exports to the outside world what it provides; it is not the business of any other package to know those details. Therefore use only <use> or <external> and not <lib> in your BuildFile; use <lib> only if there is no other choice (read: you are depending on somebody else's package and cannot have that BuildFile changed). The implication on your package is that you must <use> every package from which you #include headers from. Do not add <use>s for packages you need indirectly, the packages you use directly take care of that for you, just as you do. Also add an <export> section to export your library to other packages with a <lib>.
The net result of these steps is that SCRAM will know what libraries your package must link against, and other packages using your library will know what yours depends on without having to know the details themselves -- they get your library and everything else it needs.
The BuildFile in the new package root directory should look something like this:
<Use name=Ig_Extensions/IgQt> <External ref=Qt> <Export> <Lib name=IgFooBar> </Export>
