Changes between Initial Version and Version 1 of EncapManMkencap

Timestamp:

08/11/06 07:09:19 (16 years ago)

Author:

dclark

Comment:

--

EncapManMkencap

@@ +1 @@
+{{{
+#!html
+<H2>NAME</H2>
+
+mkencap - Encap package creation tool
+<A NAME="lbAC">&nbsp;</A>
+<H2>SYNOPSIS</H2>
+
+<B>mkencap [options] -b [-DUPCBIT] \
+<BR>
+
+<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[-m&nbsp;m4_cmd]&nbsp;[-M&nbsp;m4_outfile]&nbsp;\
+<BR>
+
+<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[-d&nbsp;download_dir]&nbsp;[-F&nbsp;environment_file]&nbsp;\
+<BR>
+
+<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[-O&nbsp;build_tree]&nbsp;[-S&nbsp;src_tree]&nbsp;profile
+<P>
+mkencap [options] \
+<BR>
+
+<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[&nbsp;-e&nbsp;[-n]&nbsp;[-a&nbsp;&quot;encapinfo_directive&nbsp;...&quot;]&nbsp;]&nbsp;\
+<BR>
+
+<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[&nbsp;-c&nbsp;[-o&nbsp;outfile]&nbsp;]&nbsp;pkgspec</B>
+<A NAME="lbAD">&nbsp;</A>
+<H2>VERSION</H2>
+
+This man page documents version 2.3 of <B>mkencap</B>.
+<A NAME="lbAE">&nbsp;</A>
+<H2>DESCRIPTION</H2>
+
+<B>mkencap</B> is a tool to help create <I>Encap</I> 2.1 packages.  It can
+create package directories, generate <I>encapinfo</I> files, and create
+package archives.
+<A NAME="lbAF">&nbsp;</A>
+<H2>MODES</H2>
+
+Any combination of these modes may be specified when <B>mkencap</B> is
+invoked.  Directory initialization is done first, if selected.  Then,
+if the <I>encapinfo</I> file is needed, it is created.  Finally, a tar
+archive is created if desired.
+<DL COMPACT>
+<DT><B>-b</B>
+
+<DD>
+Build the package from a profile.  If the <I>-b</I> option is specified,
+<I>package</I> should be the path to the file containing the package's
+profile.  (See <B>PACKAGE PROFILE OPTIONS</B> below for other related
+options.)
+<DT><B>-e</B>
+
+<DD>
+Create an <I>encapinfo</I> file in the package directory.
+(See <B>ENCAPINFO OPTIONS</B> below for other related options.)
+<DT><B>-c</B>
+
+<DD>
+Create archive.  <B>mkencap</B> will create a (optionally compressed)
+tar archive of <I>package</I>.  (See <B>ARCHIVE CREATION OPTIONS</B>
+below for other related options.)
+</DL>
+<P>
+
+If none of these options are selected, <B>mkencap</B> will create an
+<I>encapinfo</I> file and a tar archive.
+<A NAME="lbAG">&nbsp;</A>
+<H2>GENERAL OPTIONS</H2>
+
+These options may be used in combination with any other options:
+<DL COMPACT>
+<DT><B>-E encap_format</B>
+
+<DD>
+Specify the Encap package format version of the new package.  The
+default is <I>2.1</I>.
+<DT><B>-p platform</B>
+
+<DD>
+Set the package's Encap platform name to <I>platform</I>.  If this option
+is not specified, the platform name is set to that of the host that
+<B>mkencap</B> is running on.
+<DT><B>-A platform_suffix</B>
+
+<DD>
+Appends <I>platform_suffix</I> to the package's Encap platform name.
+<DT><B>-f</B>
+
+<DD>
+Force <B>mkencap</B> to overwrite an existing <I>encapinfo</I> file.
+<DT><B>-q</B>
+
+<DD>
+Quiet mode.  Only error messages are output to stdout.
+<DT><B>-s source_dir</B>
+
+<DD>
+Tells <B>mkencap</B> to use <I>source_dir</I> as the <I>Encap</I> source
+directory.  If the source is not specified but the target is,
+<B>mkencap</B> will assume the relative path from the target to the
+source is <I>encap/</I>.  If neither is specified, <B>mkencap</B> will check the
+contents of the ENCAP_SOURCE environment variable.  If that is
+not set, it will use the default set at compile-time (usually
+<I>/usr/local/encap</I>).
+<DT><B>-t target_dir</B>
+
+<DD>
+Tells <B>mkencap</B> to use <I>target_dir</I> as the <I>Encap</I> target
+directory.  If the target is not specified but the source is,
+<B>mkencap</B> will assume the relative path from the source to the
+target is <I>../</I>.  If neither is specified, <B>mkencap</B> will check the
+contents of the <B>ENCAP_TARGET</B> environment variable.  If that is
+not set, it will use the default set at compile-time (usually
+<I>/usr/local</I>).
+<DT><B>-v</B>
+
+<DD>
+Increase verbosity.  This option can be specified multiple times.
+<DT><B>-V</B>
+
+<DD>
+Print <B>mkencap</B> version and compile-time defaults.
+</DL>
+<A NAME="lbAH">&nbsp;</A>
+<H2>PACKAGE PROFILE OPTIONS</H2>
+
+These options are only meaningful when processing package profiles (see
+<I>-b</I> option above):
+<DL COMPACT>
+<DT><B>-D</B>
+
+<DD>
+Download source distribution if not already present.  The downloaded
+file is placed in the common source tree.
+<DT><B>-U</B>
+
+<DD>
+Unpack source distribution.
+<DT><B>-P</B>
+
+<DD>
+Apply any necessary patches to source distribution.
+<DT><B>-C</B>
+
+<DD>
+Configure source distribution.
+<DT><B>-B</B>
+
+<DD>
+Build source distribution.
+<DT><B>-I</B>
+
+<DD>
+Install source distribution to create an Encap package.
+(This usually needs to be done as <I>root</I>.)
+<DT><B>-T</B>
+
+<DD>
+Tidy source distribution.
+</DL>
+<P>
+
+If none of the <I>-DUPCBIT</I> options are selected, the default
+is <I>-DUPCB</I>.
+<DL COMPACT>
+<DT><B>-m m4_cmd</B>
+
+<DD>
+Use the command <I>m4_cmd</I> to preprocess the package profile.
+If the <I>-m</I> option is not specified, <B>mkencap</B> will check the
+<I>MKENCAP_M4_COMMAND</I> environment variable.  If that variable is
+unset, <B>mkencap</B> will use the string &quot;m4&quot;, which means that it will
+use the first <B>m4</B> binary available in the <I>PATH</I>.
+<P>
+<B>Note:</B>
+
+The preprocessing command must point to GNU <B>m4</B>.  If the
+first <B>m4</B> binary in your <I>PATH</I> is not GNU <B>m4</B>, you must
+use either the <I>MKENCAP_M4_COMMAND</I> environment variable or the
+<I>-m</I> option to specify the path to GNU <B>m4</B>.
+<P>
+This option can be used to simply override which <B>m4</B> binary is
+used, as in:
+<P>
+<BR>&nbsp;&nbsp;mkencap&nbsp;-m&nbsp;/usr/local/bin/m4&nbsp;-b&nbsp;pkgspec.ep
+<P>
+However, it can also be used to add options to be passed to the <B>m4</B>
+command, as in:
+<P>
+<BR>&nbsp;&nbsp;mkencap&nbsp;-m&nbsp;&quot;m4&nbsp;-Dmacro=value&quot;&nbsp;-b&nbsp;pkgspec.ep
+<DT><B>-d download_dir</B>
+
+<DD>
+Tells <B>mkencap</B> where to put source files as they are downloaded.
+If the <I>-d</I> option is not specified, <B>mkencap</B> will check the
+<I>MKENCAP_DOWNLOAD_DIR</I> environment variable.  If that variable is
+unset, <B>mkencap</B> will use the default set at compile-time (usually
+<I>/usr/local/src</I>).
+<DT><B>-F environment_file</B>
+
+<DD>
+Tells <B>mkencap</B> to read environment variable settings from
+<I>environment_file</I>.  If the <I>-F</I> option is not specified,
+<B>mkencap</B> will use the default set at compile-time (usually
+<I>/usr/local/etc/mkencap_environment</I>).
+<DT><B>-S src_tree</B>
+
+<DD>
+Tells <B>mkencap</B> where the common source tree is located.  For
+packages that can be built in a seperate directory from where the source
+code is located, the source code will be stored in the common source
+tree.  If the <I>-S</I> option is not specified, <B>mkencap</B> will check
+the <I>MKENCAP_SRC_TREE</I> environment variable.  If that variable is
+unset, <B>mkencap</B> will store the source code in the build tree.
+<DT><B>-O build_tree</B>
+
+<DD>
+Tells <B>mkencap</B> where the build tree is located.  The build tree is
+used for building packages from source code.  If the <I>-O</I> option is
+not specified, <B>mkencap</B> will check the <I>MKENCAP_BUILD_TREE</I>
+environment variable.  If that variable is unset, <B>mkencap</B> will
+use the default set at compile-time (usually <I>/usr/local/src</I>).
+<P>
+If the build tree path contains the string &quot;%p&quot;, it will be replaced
+with the platform name.
+<DT><B>-M m4_outfile</B>
+
+<DD>
+Tells <B>mkencap</B> to write the output of <B>m4</B> to the file
+<I>m4_outfile</I>.  If <I>m4_outfile</I> is &quot;-&quot;, the output will be
+written to <I>stdout</I>.
+<P>
+This option is useful for debugging problems caused by <B>m4</B>
+preprocessing.
+</DL>
+<A NAME="lbAI">&nbsp;</A>
+<H2>ENCAPINFO OPTIONS</H2>
+
+These options are only meaningful when creating an <I>encapinfo</I> file
+(see <I>-e</I> option above):
+<DL COMPACT>
+<DT><B>-n</B>
+
+<DD>
+Do not add default <I>contact</I>, <I>date</I>, and <I>platform</I> fields to
+the <I>encapinfo</I> file.
+<P>
+When adding the <I>contact</I> field, <B>mkencap</B> will first check the
+environment variable <I>ENCAP_CONTACT</I>.  If unset, it will use the
+username of the invoking user and the hostname of the host it was run on.
+<DT><B>-a encapinfo_directive ...</B>
+
+<DD>
+Adds the specified directive to the <I>encapinfo</I> file.  Syntax checking
+is done to ensure that the line is parsable.
+</DL>
+<A NAME="lbAJ">&nbsp;</A>
+<H2>ARCHIVE CREATION OPTIONS</H2>
+
+This option is only meaningful when creating an archive file (see
+<I>-c</I> option above):
+<DL COMPACT>
+<DT><B>-o outfile</B>
+
+<DD>
+Specify the output filename when creating an archive.  If the filename ends
+in <I>.tgz</I> or <I>.gz</I>, it is compressed using <B><A HREF="http://www.gzip.org/">gzip</A></B>(1).  If the
+filename ends in <I>.Z</I>, it is compressed using <B><A HREF="http://en.wikipedia.org/wiki/Compress">compress</A></B>(1).  If
+the filename ends in <I>.bz2</I>, it is compressed using <B><A HREF="http://www.bzip.org/">bzip2</A></B>(1).
+<P>
+For Encap 2.0 packages, the default is <I>pkgspec.tar.gz</I>.
+<P>
+For Encap 2.1 packages, the default is
+<I>pkgspec-encap-platform.tar.gz</I>.  The <I>platform</I> string will be
+read from the <I>encapinfo</I> file.
+</DL>
+<A NAME="lbAK">&nbsp;</A>
+<H2>EXAMPLES</H2>
+
+To create an <I>encapinfo</I> file for the package &quot;pkg-2.1&quot; with the
+directives &quot;linkname bin/foo quux&quot; and &quot;linkname man/man1/foo.1 quux.1&quot;:
+<P>
+<DL COMPACT><DT><DD>
+mkencap -ea &quot;linkname bin/foo quux&quot; \
+<BR>
+
+<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-a&nbsp;&quot;linkname&nbsp;man/man1/foo.1&nbsp;quux.1&quot;&nbsp;pkg-2.1
+</DL>
+
+<P>
+To create an <I>encapinfo</I> file for the package &quot;pkg-3.0&quot; containing
+the directives &quot;exclude bin/burfle&quot; and &quot;linkdir lib/pkg&quot;, and create
+an archive of the package in your home directory:
+<P>
+<DL COMPACT><DT><DD>
+mkencap -a &quot;exclude bin/burfle&quot; -a &quot;linkname lib/pkg&quot; \
+<BR>
+
+<BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-o&nbsp;~/pkg-3.0-encap-share.tgz&nbsp;pkg-3.0
+</DL>
+
+<A NAME="lbAL">&nbsp;</A>
+<H2>ENVIRONMENT VARIABLES</H2>
+
+<B>ENCAP_SOURCE</B>
+
+<BR>
+
+<B>ENCAP_TARGET</B>
+
+<BR>
+
+<B>ENCAP_CONTACT</B>
+
+<BR>
+
+<B>MKENCAP_DOWNLOAD_DIR</B>
+
+<BR>
+
+<B>MKENCAP_SRC_TREE</B>
+
+<BR>
+
+<B>MKENCAP_BUILD_TREE</B>
+
+<BR>
+
+<B>MKENCAP_M4_COMMAND</B>
+
+<A NAME="lbAM">&nbsp;</A>
+<H2>FILES</H2>
+
+<I>/usr/local/encap/pkgname/encapinfo</I>
+
+<BR>
+
+<I>/usr/local/etc/mkencap_environment</I>
+
+<A NAME="lbAN">&nbsp;</A>
+<H2>SEE ALSO</H2>
+
+<B><A HREF="/projects/bcfg2/wiki/EncapManEpkg">epkg</A></B>(1),
+
+<B><A HREF="/projects/bcfg2/wiki/EncapManEncapProfile">encap_profile</A></B>(5)
+
+<BR>
+
+The Encap Archive (<I><A HREF="http://www.encap.org/">http://www.encap.org/</A></I>)
+<A NAME="lbAO">&nbsp;</A>
+<H2>AUTHOR</H2>
+
+Mark D. Roth &lt;<A HREF="mailto:[email protected]">[email protected]</A>&gt;
+</BODY>
+}}}