michael@13: ##
michael@13: ##  release -- OpenPKG Release Utility
michael@13: ##  Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
michael@13: ##  Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/>
michael@13: ##
michael@13: ##  Permission to use, copy, modify, and distribute this software for
michael@13: ##  any purpose with or without fee is hereby granted, provided that
michael@13: ##  the above copyright notice and this permission notice appear in all
michael@13: ##  copies.
michael@13: ##
michael@13: ##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
michael@13: ##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
michael@13: ##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
michael@13: ##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
michael@13: ##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
michael@13: ##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
michael@13: ##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
michael@13: ##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
michael@13: ##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
michael@13: ##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
michael@13: ##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
michael@13: ##  SUCH DAMAGE.
michael@13: ##
michael@13: 
michael@13: =pod
michael@13: 
michael@13: =head1 NAME
michael@13: 
michael@13: B<openpkg release> - OpenPKG Release Utility
michael@13: 
michael@13: =head1 SYNOPSIS
michael@13: 
michael@13: B<openpkg release> [B<-F>|B<--fmt> I<format>]
michael@13: 
michael@13: =head1 DESCRIPTION
michael@13: 
michael@13: The B<openpkg release> command displays the OpenPKG release tag and
michael@13: distribution URL. The release tag uniquely identifies an OpenPKG
michael@13: distribution and the distribution URL is the location where the
michael@13: distribution packages and indices are stored.
michael@13: 
michael@13: =head1 OPTIONS
michael@13: 
michael@13: =over 4
michael@13: 
michael@13: =item B<-F>, B<--fmt> I<format>
michael@13: 
michael@13: The output format specification. The argument I<format> is an arbitrary
michael@13: string which can contain the special expansion constructs "C<%t>" for
michael@13: expanding the release tag, "C<%u>" for expanding the distribution URL
michael@13: and "C<\n>" for expanding an embedded newline character. 
michael@13: The instance UUID information is also availble by expanding
michael@13: C<%r> to UUID_REGISTRY, C<%i> to UUID_INSTANCE, C<%p> to UUID_PLATFORM.
michael@13: The default I<format> is "C<OpenPKG-%t %u>".
michael@13: 
michael@13: =item B<-r>, B<--release> I<release>
michael@13: 
michael@13: The package "C<Release>" header value to use for deriving the release
michael@13: tag. The values in the F<@l_prefix@/etc/openpkg/release> file and the
michael@13: "C<Release>" header of the bootstrap package B<openpkg> are ignored if
michael@13: this option is used.
michael@13: 
michael@13: =back
michael@13: 
michael@13: =head1 FILES
michael@13: 
michael@13: =over 4
michael@13: 
michael@13: =item F<@l_prefix@/etc/openpkg/release>
michael@13: 
michael@13: This optional configuration file can be used to explicitly set values
michael@13: for the OpenPKG release tag and distribution URLs. It consists of lines
michael@13: with variable name/value pairs. The following configuration variables
michael@13: are recognized:
michael@13: 
michael@13: =over 4
michael@13: 
michael@13: =item B<TAG=>I<tag>
michael@13: 
michael@13: The default I<tag> is automatically derived from the "C<Version>" header
michael@13: of the OpenPKG bootstrap package B<openpkg>. One usually only sets this
michael@13: explicitly to a value if a bootstrap package is used from a foreign
michael@13: distribution version.
michael@13: 
michael@13: =item B<URL=>I<url>
michael@13: 
michael@13: The fully-qualified distribution URL based on either the "C<ftp>",
michael@13: "C<http>" or "C<file>" URL schemes. If I<url> contains a trailing
michael@13: "C</*>", this is expanded according to the I<tag> value of the B<TAG>
michael@13: variable and the corresponding filesystem layout on C<ftp.openpkg.org>.
michael@13: The default I<url> is "C<ftp://ftp.openpkg.org/*>".
michael@13: 
michael@13: =over
michael@13: 
michael@13: =back
michael@13: 
michael@13: =head1 EXAMPLE
michael@13: 
michael@13:  $ openpkg release
michael@13:  OpenPKG-CURRENT ftp://ftp.openpkg.org/current/SRC/
michael@13: 
michael@13:  $ openpkg release --fmt=%t
michael@13:  CURRENT
michael@13: 
michael@13:  $ openpkg release --fmt=%u
michael@13:  ftp://ftp.openpkg.org/current/SRC/
michael@13: 
michael@13:  $ openpkg release --fmt="OpenPKG %t is located at:\\n%u"
michael@13:  OpenPKG CURRENT is located at:
michael@13:  ftp://ftp.openpkg.org/current/SRC/
michael@13: 
michael@13:  $ openpkg release --release=2.5.4 --fmt=%t
michael@13:  2.5-RELEASE
michael@13: 
michael@13:  $ cat /openpkg/etc/openpkg/release
michael@13:  TAG=2-STABLE-20060622
michael@13:  URL=ftp://ftp.example.com/mirror/openpkg.org/*
michael@13: 
michael@13: =head1 SEE ALSO
michael@13: 
michael@13: uuid(8)
michael@13: 
michael@13: =head1 HISTORY
michael@13: 
michael@13: The B<openpkg release> command first appeared in B<OpenPKG 2-STABLE-20060622>.
michael@13: 
michael@13: =cut
michael@13: