Terminology
Here are some terms used throughout the documentation. They are perhaps more precisely defined than usual:
- package
A collection of source code and auxiliary files that compiles or otherwise installs programs, libraries and/or data files.
There are many examples: apache, mysql, iota, etc.
- depend
As with other common packaging systems (Debian, RPM), a package X can depend on another package Y, meaning that X cannot be installed until Y has been installed and usually Y will be installed automatically if X is requested.
- playpen
A complete mirror of the site, used for development and testing. Each developer typically has a playpen on his or her box that they use for developing/testing new features, or debugging problems.
Sometimes called a sandbox.
- cluster
A group of computers which act together to provide something to a user, like a website.
- Package Archive
A place where all the packages are held. It contains all the files written by the packaging authors ( often the same as the project authors ) plus the raw source code from the web, and a package-list so you can easily find the latest version of a given package.
A package archive is just another wigwam project. As such the files found there are checked into CVS. For examle the public wigwam package archive is checked in as the module wigwam-package-archive.
There are files ending with .urls which contain web addresses for the official download sites for the remaining files. However, Because all the files are downloaded to the archive, and copies stored there, playpens do not depend on the continued availability of the packages on the Internet, only the availability of the archive. ( so if you back yours up, you can always rebuild any version of your project. )
Playpens may use more than one package archive simultaneously; the first package archive listed takes precendence if two identically numbered packages are available. Also if the package archive listed is the word 'LOCAL' it will be interpreted to be an in project package archive located in $PLAYPEN_ROOT/package-archive ( as of wigwam v3.0.48 )
If you wish to use a package archive that is protected with HTTP Basic Authentication, do one of the following:
Use the standard format for embedding usernames and passwords in a URL:
http://USERNAME:PASSWORD@HOST/PATH/...
Use auth-disk-http: instead of http: and auth-disk-https: instead of https:. The first time you use the playpen you will be prompted for user-names and passwords. After that the username and password will be stored on your local disk.
Use auth-env-http: instead of http: and auth-env-https: instead of https:. When you setup-env will be prompted for user-names and passwords, then the data will be stored in your environment.
- building
The process of compiling the package. Generally that means taking the original authors' source code, applying any patches we might have, and then converting that to machine readable format. This includes a "source code configuration phase" to determine what flags are needed during actual compilation.
Building doesn't really have any direct effect on the project, but before you install a package, it must be built, and building takes a lot longer than installing. To save time, two conflicting packages can be built, and either one can be installed in short notice. This is often used to switch back and forth quickly between two versions of a piece of software.
For most packages, building consists of running these commands:
but with several options, and some packages (e.g., "raw" and "service" type packages) do not even conform to this../configure makeTODO: examples would be helpful
This process downloads the unbuilt package sources from the project's archive to ext/packages/, then it unpacks and compiles under ext/build/$package-$version. It should not modify any file outside of these two directories.
- installing
The process of copying the public binaries, libraries and data files into publicly accessible areas. Building should only affect files under ext/build. Installed packages must not use ext/packages or ext/build.
For most packages, installing consists of running the command:
but with several options.make install
TODO: examples would be helpful
Packages should never install anything outside of ext/.
- publishing
The process of
updating packages and source code,
rebuilding and reinstalling the upgraded packages,
restarting services on the actual live servers.
- service
A package or part of a project which has some functionality that can be stopped, started or restarted. Services are controlled using servicectl.
Note that services are not the same as server programs. For example, a commonly used service is static_apache, which runs the Apache web server in a configuration suitable for serving HTML, images, and other static content. This service is provided by the package service_static_apache. The actual apache program is provided by the apache package, which is different from the service_static_apache package. This is because there are other services (e.g., service_mod_perl_apache and service_jserv_apache) which run apache in different configurations for different purposes.
Most services are provided by packages whose names start with "service_". These packages will depend on the packages which provide the program they run. For example, the service_mysqld package depends on the mysqld package.
Services can also be provided by the project itself, so that custom project-specific programs can be controlled in the same way as the other services. When the service is provided by the project, the source code for should be in $PLAYPEN_ROOT/src, and the service configuration should be in $PLAYPEN_ROOT/services/$SERVICE_NAME.
- md5sum
A checksum used in Wigwam to determine whether a file is correct. The program md5sum will tell you the md5 checksum (md5sum) of any stream of data or a file. It is a 32-digit hexidecimal number (with the a-f characters lowercase). If the md5sums of two files are identical, it is likely that the files are also identical. If the md5sum is different, the files are definitely different. This property is used to verify the integrity of downloaded packages.