README

Proto -- making your Perl 6 work slightly easier

Proto is a hyper-lightweight dependency tracking and module installation
system.  It helps you set up a running environment where you can play
with Rakudo Perl 6 and library modules with minimal hassle.  It's not
comprehensive like Parrot's Plumage will be, it's an unreliable
prototype, as the name suggests.  It is currently experimenting with the
module ecosystem of Rakudo *, which should accommodate multiple
instances of modules distinguished by :auth and :ver name parts.

Proto can bootstrap on Unix and Windows from a single file download, or
by cloning its Github repository.  It keeps terminal output concise and
has few commands and options.  You can use it to:

 1. Download, compile and install Parrot and Rakudo
 2. Download, compile, test and install Perl 6 modules
 3. Create new modules (in projects, with tests)

To install Proto, get the main script with this command (or a browser)
(all on one line without the \ if not in a Unix compatible shell):

 perl -MLWP::UserAgent -e"LWP::UserAgent->new->mirror( \
    'http://github.com/masak/proto/raw/master/proto', 'proto.pl')"

To configure proto, type the following at the prompt:

 perl proto.pl configure proto

To then install Rakudo (and Parrot), type the following at the prompt:

 perl proto.pl install rakudo

If you already had a Rakudo installed, instead of having proto install
it again, you can simply adjust ~/.perl6/proto/proto.conf to tell it 
where Rakudo and Parrot are on the system.

Installation of Parrot and Rakudo is merely a convenience; what proto
was really built for is installing modules. The command

 perl proto.pl install <module> [<module> ...]

will look among its list of registered modules for <module>, and
download and build whatever it finds.

Should the downloaded module happen to explicitly depend on other
modules, these will be downloaded and built before the dependent module
is built. And so on, until it all bottoms out.

The upgrade command

 perl proto.pl upgrade <module>

will check the module <module> and all that depend on it for upgrades,
and rebuild them in the required order. Omit the name of the module, and
all your installed modules will be upgraded.

See the file PIONEER for how to set up your project with proto, or let
the create-new-project script make one semi-automatically. TODO: convert
create-new-project (a bash script) into another Perl 6 module.

Removing a module is as simple as

 perl proto.pl uninstall <module>

If a dependency cycle is detected during the download process, the
install is aborted and the dependency cycle is described. It might still
be possible to install all modules despite the cycle, but the mere fact
that there's a cycle merits human attention.

There are many things which proto does not do. Even so, it is the hope
of its authors that it might be of some use, and make Perl 6 poets bold
in splitting up their work into logical independent units.

How to add your project to projects.list and poc-projects.list:

 1.) Fork the proto repository into your github account (press Fork button.)
 2.) Clone your new repository to your local hard drive:
   $ git clone git@github.com:yourusername/proto.git
   ( don't forget to change yourusername to your own username.)
 3.) Edit the projects.list file and add your project in YAML format.
 4.) Commit your changes.
   $ git commit -a -m 'added my project'
   $ git push
 5.) Checkout the pls branch:
   $ git fetch
   $ git checkout pls
 6.) Edit the poc-projects.list file and add your project in JSON format.
 7.) Commit your changes.
   $ git commit -a -m 'added my project'
   $ git push
 8.) On your github page, click "Pull Request", and submit your request.

After sending the Pull Request, the Proto/pls developers will review your
changes and merge them with the primary repo.

Proto is (C) Copyright 2010 by the Proto contributors (as listed in
AUTHORS). The license is Artistic 2.0; see LICENCE.