Permalink
Browse files

Rewrote the README in org-mode format.

  • Loading branch information...
1 parent 2da2f5f commit 62525895eb83d0f590971832b72df7f675b18eec @juster committed Feb 5, 2011
Showing with 144 additions and 104 deletions.
  1. +1 −1 .shipit
  2. +143 −103 README
View
@@ -1,3 +1,3 @@
-steps = FindVersion, ChangeVersion, DistTest, PodReadme, Commit, Tag, MakeDist, UploadCPAN
+steps = FindVersion, ChangeVersion, DistTest, Commit, Tag, MakeDist, UploadCPAN
git.tagpattern = v%v
git.push_to = origin
View
246 README
@@ -1,131 +1,171 @@
-NAME
- CPANPLUS::Dist::Arch - CPANPLUS backend for building Archlinux pacman
- packages
-
-SYNOPSIS
- (First, setup cpan to use us automatically)
- $ setupdistarch
-
- (Install the module as a pacman package)
- $ cpanp -i Perl::Module::Here
-
- (Use cpan2dist to make a package, but don't install it)
- $ cpan2dist Acme::Bleach
-
- (Use our included cpan2aur to make a source package in current dir)
- $ cpan2aur CPANPLUS::Dist::Arch
-
- (In case we need to customize our package build, create a directory
- with a template we can use for future versions.)
- $ cpan2aur -d CPANPLUS::Dist::Arch
- ==> Creating new directory for CPANPLUS::Dist::Arch...
- -> Looking up module for CPANPLUS::Dist::Arch on CPAN...
- Running [/usr/bin/perl /usr/bin/perlbin/core/cpanp-run-perl /home/juster/.cpanplus/5.10.1/build/CPANPLUS-Dist-Arch-0.16/Makefile.PL INSTALLDIRS=site]...
- Writing Makefile for CPANPLUS::Dist::Arch
- -> Creating new PKGBUILD.tt template file...
- ==> Created perl-cpanplus-dist-arch source package directory.
+-*- org -*-
+ ____ ____ _ _ _ ____ _ _ _ _
+ / ___| _ \ / \ | \ | | _ _ _| _ \(_)___| |_ _ _ / \ _ __ ___| |__
+| | | |_) / _ \ | \| |_| |(_|_) | | | / __| __(_|_) / _ \ | '__/ __| '_ \
+| |___| __/ ___ \| |\ |_ _| _| |_| | \__ \ |_ _ _ / ___ \| | | (__| | | |
+ \____|_| /_/ \_\_| \_| |_|(_|_)____/|_|___/\__(_|_)_/ \_\_| \___|_| |_|
+
+CPANPLUS::Dist::Arch - CPANPLUS backend for building Archlinux pacman packages
+
+* Background
+
+CPAN is the name for both the repository of Perl modules mirrored
+around the world and the program that automatically installs modules
+from that international module list. CPANPLUS is the next evolution
+of the venerable CPAN shell.
+
+ArchLinux is a Linux distribution known for its minimalism. The most
+distinguishing feature of ArchLinux is its use of the "pacman" package
+managing program. Packages for pacman are created with the "makepkg"
+script which is included with "pacman".
+
+CPANPLUS::Dist::Arch is a plugin whose goal is to bridge the gap
+between the CPAN and ArchLinux. CPANPLUS is already a great tool for
+downloading modules, resolving dependencies, and installing modules.
+This module acts as a plugin, installing itself into the CPANPLUS
+internals and managing the module building and installation process.
+
+Instead of CPANPLUS's usual behavior, Perl modules are instead built as
+ArchLinux packages by using "makepkg". Instead of the straight-forward
+installation of modules by copying files into system-wide locations,
+these built packages are installed using "pacman". This offers the
+advantage of better dependency tracking and uninstallation.
+
+* Install
- (Customize the template... add a optdepends, library depends, etc.
- Just leave the rest of it alone.)
- $ cd perl-cpanplus-dist-arch
- $ ed PKGBUILD.tt
+To install this module manually follow these steps. If you have
+already downloaded and extracted the distribution tarball
+(CPANPLUS-Dist-Arch-<version>.tar.gz) in order to read this README
+file, skip to step 4.
- (Submit it to AUR! Will ask for a login username/password or remember
- the last one used)
- $ cpan2aur -u
+1) Download the distribution tarball from CPAN.
+2) Extract the tarball.
+3) *cd* into the extracted directory (CPANPLUS-Dist-Arch-<version>)
+4) Run *perl Build.PL* to create the *Build* file.
+5) Run *./Build* to build the module using the *Build* file.
+6) (Optional) Run *./Build test* to run automated self-tests.
+7) Run *./Build install* to install the perl module into a system directory.
-DESCRIPTION
- This module is used as a plugin of CPANPLUS to transparently package
- CPAN distribution files into pacman packages as they are installed. This
- module can also be used by programmers to build packages in more complex
- ways. For example, it can create source packages for the AUR by using
- the included cpan2aur program.
+#+BEGIN_EXAMPLE
-REQUIREMENTS
- You will need to have pacman installed, of course, to create package and
- to install these new packages. Pacman is included with Archlinux but can
- even be used on other Linux distributions. (see
- http://wiki.archlinux.org/index.php/Pacman)
+curl -O http://.../CPANPLUS-Dist-Arch-1.11.tar.gz
+tar xf CPANPLUS-Dist-Arch-1.11.tar.gz
+cd CPANPLUS-Dist-Arch-1.11
+perl Build.PL
+./Build
+./Build test
+sudo ./Build install
-SETUP
- Type setupdistarch at the command line to install CPAN modules as
- packages by default.
+#+END_EXAMPLE
-WHERE IS THE PACKAGE
- By default, packages are stored under the user's home directory in the
- *.cpanplus* directory. Two seperate directories are created for building
- packages and for storing the resulting package file.
+Or better yet, use a CPAN shell to do it for you! CPANminus is
+available on CPAN under the name "App-cpanminus".
- *5.10.1* represents the version of perl you used to build the package
- and *~/.cpanplus* represents the base directory chosen in your CPANPLUS
- config.
+* Setup CPANPLUS
- * Build Directory: `~/.cpanplus/5.10.1/pacman/build'
- * Package Directory: `~/.cpanplus/5.10.1/pacman/pkg'
+The steps above install this module into your system where it is
+available for use by perl. You will also need to activate
+CPANPLUS::Dist::Arch as a plugin in the CPANPLUS shell.
-CUSTOMIZATION
- You can change defaults settings machine-wide (for every user) or for
- one user or package. The machine-wide settings are set in the
- */etc/makepkg.conf* file. The user/package customizations are set using
- environment variables.
+I have included a program called 'setupdistarch' that makes this
+easier. Run the program and answer yes in order to enable
+automatic packaging of installed CPANPLUS modules.
- PKGDEST
- Override where the package files end up.
+#+BEGIN_EXAMPLE
- PACKAGER
- Override the Contributor comment line at the top of the PKGBUILD.
+$ setupdistarch
+Are you sure you want to auto-package CPAN installs? [Yn] y
+CPANPLUS will now auto-package modules.
-SUPPORT
- Email me at `<juster at cpan dot org>' or message me as *juster* on the
- Archlinux BBS at http://bbs.archlinux.org.
+#+END_EXAMPLE
- To check why the build process failed, read the build logs CPANPLUS
- keeps in `~/.cpanplus/install_logs/'. The problem may be specific to the
- module you're building and not this module.
+See the 'setupdistarch' manpage for more information.
-ACKNOWLEDGEMENTS
- This module was inspired by the perl-cpanplus-pacman package and
- CPANPLUS::Dist::Pacman by Firmicus which is available at
- http://aur.archlinux.org/packages.php?ID=5954.
+* Requirements
- This mostly started from CPANPLUS::Dist::RPM which is on Google Code at
- http://code.google.com/p/cpanplus-dist-rpm/. This was a very helpful
- starting point to try to understand the internals of CPANPLUS.
+A number of modules are required to run CPANPLUS::Dist::Arch. These
+are all included with recent versions of perl so you should not need
+to install anything before you can use it. In each table I list which
+distribution contains one or more modules. A distribution is CPAN's
+version of a package.
-CONTRIBUTORS
- Contributors are credited in detail in the ChangeLog file. The following
- people have been kind enough to submit bug reports:
+** Core Modules
- * Xenoterracide
- * IsaacG
+ - CPANPLUS
+ - Digest::MD5
+ - Pod::Select
+ - List::Util
+ - File::Path
+ - File::Copy
+ - File::stat
+ - DynaLoader
+ - IPC::Cmd
+ - version
+ - English
+ - Carp
+ - Cwd
- *Thank you for your help!*
+** Optional Template Modules
-SEE ALSO
- * AUR Package: perl-cpanplus-dist-arch
- http://aur.archlinux.org/packages.php?ID=24971
+C::D::A uses templates for creating PKGBUILD files. It is possible to
+override the template that is used in order to customize PKGBUILDs
+completely to your liking. If you do this you might want to use a
+template module instead of C::D::A's crude internal template
+engine. Template modules are searched for in this order:
- * Git Repository
- http://github.com/juster/perl-cpanplus-dist-arch
+|----------+-------------------+-------------------|
+| Priority | Module | CPAN Distribution |
+|----------+-------------------+-------------------|
+| 1 | Template::Toolkit | Template |
+| 2 | Template::Alloy | Template-Alloy |
+| 3 | Template::tiny | Template-Tiny |
+|----------+-------------------+-------------------|
- * Archlinux Perl Package Guidelines
- http://wiki.archlinux.org/index.php/Perl_Package_Guidelines
+* See Also
- * pacman
- http://wiki.archlinux.org/index.php/Pacman
+** CPANPLUS::Dist::Arch manpage
- * makepkg
- http://wiki.archlinux.org/index.php/Makepkg
+Run 'man CPANPLUS::Dist::Arch' after installing to view the manpage.
- * CPANPLUS
- http://search.cpan.org/dist/CPANPLUS/
+** AUR Package: perl-cpanplus-dist-arch
-AUTHOR
- Justin Davis `<juster at cpan dot org>'
+http://aur.archlinux.org/packages.php?ID=24971
-COPYRIGHT & LICENSE
- Copyright 2010 Justin Davis, all rights reserved.
+** Git Repository
- This program is free software; you can redistribute it and/or modify it
- under the same terms as Perl itself.
+http://github.com/juster/perl-cpanplus-dist-arch
+** Archlinux Perl Package Guidelines
+
+http://wiki.archlinux.org/index.php/Perl_Package_Guidelines
+
+** pacman
+
+http://wiki.archlinux.org/index.php/Pacman
+
+** makepkg
+
+http://wiki.archlinux.org/index.php/Makepkg
+
+** CPANPLUS
+
+http://search.cpan.org/dist/CPANPLUS/
+
+* Author
+
+Justin Davis <juster at cpan dot org>
+
+* Support
+
+Send me an e-mail if you have any questions or need help. If you
+run into any bugs please e-mail any information about them.
+
+* License and Copyright
+
+Copyright 2011 Justin Davis.
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of either: the GNU General Public License as published
+by the Free Software Foundation; or the Artistic License.
+
+See http://dev.perl.org/licenses/ for more information.

0 comments on commit 6252589

Please sign in to comment.