xcat-core/xCAT-buildkit/pods/man1/buildkit.1.pod

=head1 NAME

B<buildkit> - Used to build a software product Kit which may be used to install software in an xCAT cluster.

=head1 SYNOPSIS

B<buildkit> [B<-?>|B<-h>|B<--help>] [B<-v>|B<--version>]

To build a new Kit

B<buildkit> [B<-V>|B<--verbose]> I<subcommand> [I<kit_name>] [I<repo_name>|B<all>] [B<-l>|B<--kitloc> I<kit_location>] 

To add packages to an existing Kit.

B<buildkit> [B<-V>|B<--verbose>] I<addpkgs> I<kit_tarfile> [B<-p>|B<--pkgdir> I<package_directory_list>] [B<-k>|B<--kitversion> I<version>] [B<-r>|B<--kitrelease> I<release>] [B<-l>|B<--kitloc> I<kit_location>]

=head1 DESCRIPTION

The B<buildkit> command provides a collection of utilities that may be used to package a software product as a Kit tarfile that can be used to install software on the nodes of an xCAT cluster.  A Kit contains the product software packages, configuration and control information, and install and customization scripts.

Note: The xCAT support for Kits is only available for Linux operating systems.

You will need to run the B<buildkit> command several times with different subcommands to step through the process of building a kit:

By default the B<buildkit> subcommands will operate in the current working directory, (ie. look for files, create directories etc.).  You could specify a different location by using the "B<-l | --kitloc> I<kit_location>" option.

The I<kit_location> is the full path name of the directory that contains the kit files. You would use the same location value for all the buildkit subcommands.

For example, to create a new kit named "prodkit" in the directory /home/mykits/ I<either> run:

=over 4

=item 1.

If no location is provided then the command will create a subdirectory called "prodkit" in the current directory "/home/mykits" and the new kit files will be created there.
 
B<cd /home/mykits>

B<buildkit create prodkit> 
  
or

=item 2.

If a location is provided then the Kit files will be created there. Note that the Kit name does not necessarily have to be the directory name where the kit files are located.
	
B<buidkit create prodkit -l /home/mykits/prodkit>

=back
	 
In both cases the /home/mykits/prodkit directory is created and the inital files for the kit are created in that directory.
	  
The following example illustrates the basic process for building a new Kit. In this example we are building a Kit named "mytstkit".

=over 4

=item 1.

Change to the directory where you wish to create the Kit. 

=item 2.

Create a template directory for your kit:

B<buildkit create mytstkit>

=item 3.

Change directory to the new "mytstkit" subdirectory that was just created.

B<cd mytstkit>

=item 4.

Edit the buildkit configuration file for your kit:

B<vi buildkit.conf>

(See xCAT Kit documentation for details.)

=item 5.

Create all required files, scripts, plugins, and packages for your kit.

=item 6.

Validate your kit build configuration and fix any errors that are reported:

B<buildkit chkconfig>

=item 7.

List the repos defined in your buildkit configuration file:

B<buildkit listrepo>

=item 8.

For each repo name listed, build the repository.  Note that if you need to build repositories for OS distributions, versions, or architectures that do not match the current system, you may need to copy your kit template directory to an appropriate server to build that repository, and then copy the results back to your main build server.  For example, to build a repo named "rhels6.3" you would run the following command.

B<buildkit buildrepo rhels6.3> 

or, you can build all of the repos at one time if there are no OS or architecture dependencies for kitcomponent package builds or kitpackage builds:

B<buildkit buildrepo all>

=item 9.

Build the kit tar file:

B<buildkit buildtar>

=back

=head1 OPTIONS

=over 10

=item B<-h |--help>

Display usage message.

=item B<-k|--kitversion> I<version>

Product version.

=item B<-l|--kitloc> I<kit_location>

The directory location of the Kit files.

=item B<-p|--pkgdir> I<package_directory_list>

A comma-separated list of directory locations for product RPMs.

=item B<-r|--kitrelease> I<release>

Product release.

=item B<-V |--verbose>

Verbose mode.

=item B<-v|--version>

Command version.

=back

=head1 SUB-COMMANDS

=over 10

=item  B<create> I<kit_basename>

Creates a new kit build directory structure for kit I<kit_basename> using the location specified on the command line or the current directory.  The sample kit files from /opt/xcat/share/xcat/kits/kit_template are copied over, and the buildkit.conf file is modified for the specified I<kit_basename>.

=item  B<chkconfig>

Reads the buildkit.conf file, verifies that the file syntax is correct and that all specified files exist. 

=item  B<listrepo> 

Reads the buildkit.conf file, lists all Kit package repositories listed in the file, and reports the build status for each repository.

=item  B<buildrepo> {I<repo_name> | B<all>}

Reads the buildkit.conf file, and builds the specified Kit package repository.  The built packages are placed in the directory <kit_location>/build/kit_repodir/I<repo_name>.  If B<all> is specified, all kit repositories are built.

=item  B<cleanrepo> {I<repo_name> | B<all>}

Reads the buildkit.conf file, and deletes all the package files and package meta data files from the <kit_location>/build/kit_repodir/I<repo_name> directory.  If B<all> is specified, all kit repository files are deleted.

=item  B<buildtar> 

Reads the buildkit.conf file, validates that all kit repositories have been built, and builds the Kit tar file <kit_location>/I<kitname>.tar.bz2.

=item  B<cleantar> 

Reads the <kit_location>/buildkit.conf file and I<deletes> the following:

=over 4

- Kit tar files matching <kit_location>/I<kit_name*.tar.bz2>.

- <kit_location>/build/I<kit_name>

- <kit_location>/rpmbuild

- <kit_location>/tmp

- <kit_location>/debbuild 

=back

Caution:  Make sure you back up any tar files you would like to keep before running this subcommand.

=item  B<cleanall>

Equivalent to running B<buildkit cleanrepo all> and B<buildkit cleantar>.

=item  B<addpkgs> 

I<kit_tarfile> {B<-p> | B<--pkgdir> I<package_directory_list>} [B<-k> | B<--kitversion> I<version>] [B<-r> | B<--kitrelease> I<release>]

Add product package rpms to a previously built kit tar file.  This is used for partial product kits that are built and shipped separately from the product packages, and are identified with a I<kit_tarfile> name of I<kitname>.B<NEED_PRODUCT_PKGS.tar.bz2>. Optionally, change the kit release and version values when building the new kit tarfile.  If kitcomponent version and/or release values are defaulted to the kit values, those will also be changed and new kitcomponent rpms will be built.  If kit or kitcomponent scripts, plugins, or other files specify name, release, or version substitution strings, these will all be replaced with the new values when built into the new complete kit tarfile I<kit_location>/I<new_kitname>.B<tar.bz2>.

=back

=head1 RETURN VALUE

=over 3

=item <B>0

The command completed successfully.

=item <B>1

An error has occurred.

=back

=head1 EXAMPLES

=over 3

=item 1.

To create the sample kit shipped with the xCAT-buildkit rpm on a RHELS 6.3 server and naming it B<mykit>, run the following commands:

B<cd /home/myuserid/kits>

B<buildkit create mykit>

B<cd mykit>

B<vi buildkit.conf>

B<buildkit chkconfig>

B<buildkit listrepo>

B<buildkit buildrepo all >

B<buildkit buildtar>

=item 2.

To clean up a kit repository directory after build failures on a RHELS 6.3 server to prepare for a new kit repository build, run:

B<buildkit cleanrepo rhels6.3>

=item 3.

To clean up all kit build files, including a previously built kit tar file, run

B<buildkit cleanall>

=item 4.

To create a kit named "tstkit" located in /home/foobar/tstkit instead of the current working directory.

B<buildkit create tstkit -l /home/foobar/tstkit>

=back

=head1 FILES

/opt/xcat/bin/buildkit

/opt/xcat/share/xcat/kits/kit_template

/opt/xcat/share/xcat/kits/kitcomponent.spec.template

<kit location>/buildkit.conf

<kit location>/build/I<kitname>/kit.conf

<kit location>/I<kitname>.tar.bz2


=head1 SEE ALSO

addkit(1), lskit(1), rmkit(1), addkitcomp(1), rmkitcomp(1), chkkitcomp(1)