michael@428: ##
michael@428: ##  mirror.pod -- OpenPKG Package Mirroring
michael@428: ##  Copyright (c) 2011-2012 OpenPKG GmbH <http://openpkg.com/>
michael@428: ##
michael@428: ##  This software is property of the OpenPKG GmbH, DE MUC HRB 160208.
michael@428: ##  All rights reserved. Licenses which grant limited permission to use,
michael@428: ##  copy, modify and distribute this software are available from the
michael@428: ##  OpenPKG GmbH.
michael@428: ##
michael@428: ##  THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
michael@428: ##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
michael@428: ##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
michael@428: ##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
michael@428: ##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
michael@428: ##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
michael@428: ##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
michael@428: ##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
michael@428: ##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
michael@428: ##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
michael@428: ##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
michael@428: ##  SUCH DAMAGE.
michael@428: ##
michael@428: 
michael@428: =pod
michael@428: 
michael@428: =head1 NAME
michael@428: 
michael@428: B<openpkg mirror> - B<OpenPKG> Package Mirroring
michael@428: 
michael@428: =head1 SYNOPSIS
michael@428: 
michael@428: B<openpkg>
michael@428: B<mirror>
michael@428: [B<-h>]
michael@428: [B<-f>]
michael@428: [B<-q>]
michael@428: [B<-C> I<local-cache-file>]
michael@428: [B<-r> I<remote-url>]
michael@428: [B<-p> I<remote-url-prefix>]
michael@428: I<local-dir-prefix> ...
michael@428: 
michael@428: =head1 DESCRIPTION
michael@428: 
michael@428: The B<openpkg mirror> tool is a frontend for mirroring OpenPKG
michael@428: repositories, based on the OpenPKG XML/RDF index files B<openpkg
michael@428: index -S -T -D> creates. The resulting mirror can then be used with
michael@428: B<openpkg build>.
michael@428: 
michael@428: =head1 COMMAND LINE ARGUMENTS
michael@428: 
michael@428: The following command line options and arguments exist:
michael@428: 
michael@428: =over 4
michael@428: 
michael@428: =item B<-h>
michael@428: 
michael@428: Print usage help.
michael@428: 
michael@428: =item B<-f>
michael@428: 
michael@428: Force deletion of local files, even if more than 30% of the existing
michael@428: local files have to be removed.
michael@428: 
michael@428: =item B<-q>
michael@428: 
michael@428: More quiet operation, i.e., do not print interactive download progress
michael@428: bars.
michael@428: 
michael@428: =item B<-C> I<local-cache-file>
michael@428: 
michael@428: Use the text-file I<local-cache-file> for caching size/mtime/MD5
michael@428: information of local files in order to especially avoid the expensive
michael@428: re-calculation of MD5 message digests of local files on every mirror
michael@428: operation. It is strongly advised to use such a cache. Do NOT place
michael@428: I<local-cache-file> under I<local-dir-prefix>.
michael@428: 
michael@428: =item B<-r> I<remote-url>
michael@428: 
michael@428: The OpenPKG repository URL. By default the same URL as for B<openpkg
michael@428: build> is used: C<http://download.openpkg.org/stacks/current/source/>
michael@428: 
michael@428: =item B<-p> I<remote-url-prefix>
michael@428: 
michael@428: In case the I<remote-url> (option B<-r> above) points NOT to a
michael@428: root/base directory of the remote repository, it is required to
michael@428: provide the corresponding base directory I<remote-url-prefix> in
michael@428: order to allow all remote paths to be correctly mapped to sub-paths
michael@428: under I<local-dir-prefix>. By default I<remote-url-prefix> is
michael@428: just I<remote-url>. For the public OpenPKG default repository URL
michael@428: C<http://download.openpkg.org/stacks/current/source/> the corresponding
michael@428: I<remote-url-prefix> is C<http://download.openpkg.org/>.
michael@428: 
michael@428: =item I<local-dir-prefix>
michael@428: 
michael@428: The local base directory under which the mirror is established.
michael@428: Content-wise it directly corresponds to I<remote-url-prefix> (option
michael@428: B<-p> above).
michael@428: 
michael@428: =back
michael@428: 
michael@428: =head1 EXAMPLE
michael@428: 
michael@428: The following command mirrors the public OpenPKG-CURRENT repository
michael@428: files from download.openpkg.org to the local directory F<download/>. The
michael@428: prefix specification is important as the OpenPKG-CURRENT stack index
michael@428: points upwards.
michael@428: 
michael@428:  $ openpkg mirror \
michael@428:    -C download.cache \
michael@428:    -r http://download.openpkg.org/stacks/current/source/ \
michael@428:    -p http://download.openpkg.org/ \
michael@428:    download/ 
michael@428: 
michael@428: The mirror now can be used with B<openpkg build>:
michael@428: 
michael@428:  $ openpkg build \
michael@428:    -r file://`pwd`/download/stacks/current/source/ \
michael@428:    -Uaq | sh
michael@428: 
michael@428: =head1 SEE ALSO
michael@428: 
michael@428: index(8).
michael@428: 
michael@428: =head1 HISTORY
michael@428: 
michael@428: The B<openpkg mirror> command was invented in May 2012 by I<Ralf
michael@428: S.  Engelschall> E<lt>rse@engelschall.comE<gt> for use inside the
michael@428: B<OpenPKG> project E<lt>http://www.openpkg.org/E<gt>.
michael@428: 
michael@428: =head1 AUTHORS
michael@428: 
michael@428:  Ralf S. Engelschall
michael@428:  rse@engelschall.com
michael@428:  www.engelschall.com
michael@428: 
michael@428: =cut
michael@428: