Browse files

Merge branch 'soh-cah-toa/interactive'

  • Loading branch information...
2 parents 13e45b8 + 8b12c43 commit 21b4be64ee2ccf92ce7cd135af91162a22ca0418 @soh-cah-toa soh-cah-toa committed Oct 18, 2011
@@ -1,4 +1,4 @@
-### Looking for something to work on? See TASKS.
+### Looking for something to work on? See TASKS.
### This file is more of a "don't forget to do this" list.
@@ -141,7 +141,7 @@ Plumage:
* Generate .pc files if module install type does not automatically do so
* Hmmm, seems to be some fail here WRT standardizing lib names ...
* Documentation
- * Hacking docs (WIP)
+ * Add a tutorial/examples document
* Relationship between plumage and distutils/make/etc.
* Test Suite
@@ -152,7 +152,6 @@ Plumage:
* Improve harness output
* Misc suggestions
* Merge Plumage .pbc's all together into executable using pbc_merge
- * Make Plumage itself installable
* Avoid asking questions (after first setup?) if at all possible
* Recommendations ("optional dependencies") should not abort top-level
install if they fail to install
@@ -168,6 +167,26 @@ Plumage:
* From #perl6:
* mberends does not like adding directories to PATH
mberends does 'sudo ln -s <parrot_install>/bin/perl6 /usr/local/bin' instead
+* Rename --ignore-fail=<stage>=0 to --no-ignore-fail=<stage> as this is a more common
+ convention and is much cleaner
+* Support temporary and permanent modification of config file
+* Fully document usage in docs/interactive.pod
+* Set version to 1.0 after soh-cah-toa/interactive is merged into master
+ * Display Plumage version in welcome message (update example in docs/interactive.pod)
+* Move all perldoc to top of file so code is easier to read
+* Improve output messages so that they don't try to sound like a real person talking
+ because this is really childish.
+* Reword all comments that say Plumage is the "module ecosystem" because that's not
+ true: it's a package manager for the module ecosystem
+* Cleanup code for probe tests
@@ -0,0 +1,149 @@
+=begin pod
+=head1 Using the Plumage Interactive Command-Line Interface
+In addition to the basic single command interface from the shell, Plumage
+also provides an interactive command-line interface (CLI). If you need to
+run several commands, you will probably feel more comfortable with the CLI
+rather than continually invoking Plumage for each command.
+The CLI is invoked by default when no commands have been specified.
+Additionally, you can start an interactive session by explicitly specifying the
+C<cli> command. However, this is a bit redundant so it's easier to just not
+specify a command.
+=head2 Recognized Commands
+Any command that can be used from the shell interface can be invoked from the
+CLI as well. The CLI also allows you to change the config file either just
+temporarily or permanently.
+=head2 Examples
+After you've started Plumage, you will be greeted by the welcome message.
+=begin code
+ Plumage: Package Manager for Parrot
+ Copyright (C) 2009-2011, Parrot Foundation.
+ Enter 'help' for help or see docs/interactive.pod for further information.
+ plumage>
+=end code
+As the above message suggests, if you aren't sure of something, use the C<help>
+=begin code
+ plumage> help
+ List of commands:
+ Query metadata and project info:
+ projects Lists all known projects.
+ status [<project>] Shows status of <project> (defaults to all).
+ info <project> Displays detailed description of <project>.
+ metadata <project> Displays JSON metadata for <project>.
+ show-deps <project> Shows dependencies for <project>.
+ project-dir <project> Displays top directory for <project>.
+ Perform actions on a project:
+ fetch <project> Downloads source code for <project>.
+ update <project> Updates source code for <project> (falls back to fetch).
+ configure <project> Configures source code for <project> (runs 'update' first).
+ build <project> Builds <project> in current directory (runs 'configure' first).
+ test <project> Runs test suite for <project> (runs 'build' first).
+ smoke <project> Sends test results to Parrot's Smolder server (runs 'build' first).
+ install <project> Installs <project> (runs 'test' first).
+ uninstall <project> Uninstalls <project> from system (not always available).
+ clean <project> Performs basic cleanup of source tree for <project>.
+ realclean <project> Removes all generated files during the build process for <project>.
+ Get information about Plumage:
+ version Displays Plumage version and copyright statement.
+ help [<command>] Displays a help message on <command> usage (defaults to all).
+=end code
+Suppose you want to try a new programming language but aren't sure which. Let's
+see what's available.
+=begin code
+ plumage> projects
+ Known projects:
+ Close Systems programming language (C-like) for the Parrot VM
+ bf Brainfuck
+ blizkost Embed Perl 5 in Parrot, exposed as a standard HLL
+ cardinal Cardinal - Ruby compiler for Parrot
+ chitchat ChitChat
+ dbm-dynpmcs dynpmc interface to dbm-like databases.
+ decnum-dynpmcs Set of decimal arithmetic PMCs for the Parrot VM
+ digest-dynpmcs Set of message-digest dynpmcs for the Parrot VM.
+ ecmascript aka JavaScript
+ forth Forth on Parrot
+ fun An even happier Joy
+ gil Generic Imperative Language
+ hq9plus HQ9plus is a non turing-complete joke language
+ kakapo Run-time library for NQP programs on the Parrot VM
+ kea Factor on Parrot
+ lolcode Lolcode
+ lua Lua on Parrot
+ lua-batteries Libraries for Lua on Parrot
+ # Output truncated for brevity
+=end code
+As you can see, the C<projects> command lists all the projects in the
+ecosystem. Maybe you're feeling a little silly and want to write some
+LOLCODE. Let's find out a little bit more about LOLCODE.
+=begin code
+ plumage> info lolcode
+ Name : lolcode
+ Version : HEAD
+ Summary : Lolcode
+ Author : Parrot Foundation
+ URL :
+ License : Artistic License 2.0
+ Description : Lolcode
+=end code
+Looks like someone was lazy and didn't fully fill out the LOLCODE metadata
+file. That's alright, it'll be a surprise!
+=begin code
+ plumage> install lolcode
+ /usr/bin/git clone git:// /home/foo/.parrot/plumage/build/lolcode
+ Cloning into /home/foo/.parrot/plumage/build/lolcode...
+ /usr/bin/git submodule update --init
+ Successful.
+ Configuration not required for lolcode.
+ Successful.
+ # Output truncated for brevity
+=end code
+This builds, tests, and installs a particular project/module; in this case,
+C<lolcode>. It could be that you're not really in a lolcatz mood right now.
+Uninstalling a project is done with the aptly named C<uninstall> command.
+=begin code
+ plumage> uninstall lolcode
+ Uninstalling lolcode ...
+ /home/foo/bin/bin/parrot setup.pir uninstall
+ Successful.
+=end code
+=end pod
@@ -13,78 +13,78 @@ ecosystem.
\fB-h\fR, \fB--help\fR
-Print a helpful usage message.
+Displays a help message on command usage.
\fB\-c\fR, \fB\-\-config\-file\fR=\fIPATH\fR
-Read additional config file.
+Reads additional config file in \fIPATH\fR.
\fB-i\fR, \fB\-\-ignore\-fail\fR
-Ignore any failing build stages.
+Ignores any failed build stages.
\fB-i\fR, \fB\-\-ignore\-fail\fR=\fISTAGE\fR
-Ignore failures only in a particular stage. May be repeated to select more than
-one stage.
+Ignores failures only for \fISTAGE\fR (may be repeated to select more than one
\fB-i\fR, \fB\-\-ignore\-fail\fR=\fISTAGE\fR=\fI0\fR
-Don't ignore failues in this stage.
+Doesn't ignore failures in \fISTAGE\fR.
-.SS Query metadata/project info:
+.SS Query metadata and project info:
-List all known projects.
+Lists all known projects.
\fBstatus\fR [\fIPROJECT\fR]
-Show status of projects. Defaults to all.
+Shows status of \fIPROJECT\fR (defaults to all).
\fBinfo\fR \fIPROJECT\fR
-Print summary about a particular project.
+Displays detailed description of \fIPROJECT\fR.
\fBmetadata\fR \fIPROJECT\fR
-Print JSON metadata about a particular project.
+Displays JSON metadata for \fIPROJECT\fR.
-\fBshowdeps\fR \fIPROJECT\fR
-Show dependency resolution for a project.
+\fBshow-deps\fR \fIPROJECT\fR
+Shows dependencies for \fIPROJECT\fR.
\fBproject-dir\fR \fIPROJECT\fR
-Print project's top directory.
+Displays top directory for \fIPROJECT\fR.
.SS Perform actions on a project:
\fBfetch\fR \fIPROJECT\fR
-Download source.
+Downloads source code for \fIPROJECT\fR.
\fBupdate\fR \fIPROJECT\fR
-Update source. Falls back to fetch.
+Updates source code for \fIPROJECT\fR (falls back to fetch).
\fBconfigure\fR \fIPROJECT\fR
-Configure source. Updates first.
+Configures source code for \fIPROJECT\fR (runs 'update' first).
\fBbuild\fR \fIPROJECT\fR
-Build project from source. Configures first.
+Builds \fIPROJECT\fR in current directory (runs 'configure' first).
\fBtest\fR \fIPROJECT\fR
-Test build project. Builds first.
+Runs test suite for \fIPROJECT\fR (runs 'build' first).
\fBsmoke\fR \fIPROJECT\fR
-Smoke test project. Builds first.
+Sends test results to Parrot's Smolder server (runs 'build' first).
\fBinstall\fR \fIPROJECT\fR
-Install built files. Tests first.
+Installs \fIPROJECT\fR (runs 'test' first).
\fBuninstall\fR \fIPROJECT\fR
-Uninstall installed files. Not always available.
+Uninstalls \fIPROJECT\fR from system (not always available).
\fBclean\fR \fIPROJECT\fR
-Clean source tree.
+Performs basic cleanup of source tree for \fIPROJECT\fR.
\fBrealclean\fR \fIPROJECT\fR
-Clobber/realclean source tree.
+Removes all generated files during the build process for \fIPROJECT\fR.
.SS Get info about Plumage itself:
-Print program version and copyright.
+Displays Plumage version and copyright statement.
\fBhelp\fR [\fICOMMAND\fR]
-Print a helpful usage message.
+Displays a help message on \fICOMMAND\fR usage (defaults to all).
Written by Geoffrey Broadwell.
@@ -103,5 +103,4 @@ For further information, please see LICENSE or visit
.UE .
Oops, something went wrong.

0 comments on commit 21b4be6

Please sign in to comment.