Using Metro

In the QuickStartGuide, we’ve already seen how to use Metro to build stages, but now we’re going to take a look at how everything comes together and how Metro utilizes information in the Metro data files to build particular targets.

Metro Classes and Targets

All of the “targets” that Metro builds are stored in /usr/lib/metro/specs/targets. Here is a list of all the targets currently available:

Git Snapshot Functionality

Metro’s snapshot functionality is defined in the file /usr/lib/metro/specs/targets/snapshot.spec. Here is an example spec file that would generate a snapshot of a git repository:

[section target]

: snapshot
name: funtoo-$[target/version]
type: git

[section git]

name: portage
remote: git://github.com/funtoo/portage.git
branch: funtoo.org
options: pull

One would typically use this conf file along with a target/version specified on the command-line, as follows:

# metro USER-snapshot-funtoo.conf target/version: 2009.01.01

Snapshot Target Section

In the target section above, the target is set to snapshot, which informs Metro what it is generating and allows Metro to find the correct scripts to perform the snapshot. target/type is set to git, which tells the Metro scripts that it is generating a snapshot of a git-based Portage repository. The target/name value is set to funtoo-$[target/version] – this value is used to determine the filename of the resultant Portage snapshot tarball.

Snapshot Git Section

The snapshot git section defines several variables that are required for Metro’s git snapshot functionality. git/remote defines the location of the upstream repository that is to be snapshotted, and git/branch defines the git named branch or SHA1 to snapshot.

In order to conserve bandwidth and improve efficiency, the snapshot git target will clone the remote git repository only when it does not exist in a Metro local git cache directory. This Metro local git cache directory is defined in the path/cache/git variable which in turn is defined in /etc/metro/metro.conf. The variable git/name in our conf file above defines what directory name Metro will look for inside path/cache/git – or create, if a git repository does not yet exist.

Git Snapshot Walkthrough

Assuming that path/cache/git is set to /root/git/cached in /etc/metro/metro.conf, let’s walk through the behavior of Metro’s git target. First, Metro will look in /root/git/cached/portage (portage comes from the git/name value) to see if a git repository exists there. If it doesn’t exist, Metro will create the repository by cloning git://gitub.com/funtoo/portage.git. Next, Metro will check to see if the local branch funtoo.org exists. If it doesn’t, Metro will create a local branch named funtoo.org corresponding to the remote branch origin/funtoo.org.

After this, Metro will ensure that the funtoo.org branch is active. Next, Metro will see if pull is specified in git/options. Note that I recommend you specify the pull option unless you are manually managing your cached git repositories. If this option is specified, Metro will perform a git pull to ensure that the funtoo.org branch is up-to-date with the upstream funtoo.org branch. Then, Metro will generate a .tar.bz2 archive of the funtoo.org branch of the git repository at /root/git/cached/portage and store it in $[path/mirror/snapshot]/funtoo-$[target/version].tar.bz2.

Rsync Snapshot Type

One would typically use the rsync snapshot type if one wanted to create a snapshot from a local Portage tree that existed on the filesystem but is not in a git repository. Alternatively, the rsync snapshot type can be used to grab a remote Portage tree using rsync. If you wanted to create a snapshot of your current Portage tree in /usr/portage, an example configuration file might look like this:

[section target]

: snapshot
name: funtoo-$[target/version]
type: rsync

[section rsync]

path: /usr/portage

You would use the configuration file like this:

# metro USER-rsync-snapshot.conf target/version: 2009.01.01

To use the rsync target, ensure that rsync/path points to a local filesystem location or a remote rsync URL (beginning with rsync://) that holds a Portage tree.