=pod

=for comment DO NOT EDIT. This Pod was generated by Swim. See http://github.com/ingydotnet/swim-pm#readme

=encoding utf8

=head1 Name

Lola - The Local-Language Environment Manager

=head1 Synopsis

$ lola help                 # Get lola command help
$ lola js v0.10.24 -g       # Use Node.js v0.10.24 as the global default
$ lola py 2.5.6             # Use Python 2.5.6 for this shell session
$ lola pl 5.14.0 .          # Use Perl 5.14.0 under this directory
$ lola rb 1.9 ~             # Use Ruby 1.9 when run under $HOME
$ lola show pl              # Show info for Perl5
$ lola show --all           # Show info for all languages
$ lola install pl 5.18.1    # Install Perl 5.18.1

=head1 Description

Lola is a generic Bcal Bnguage environment manager. It lets you:

=over

=item * Install Bash, Node.js, Perl(5 & 6), Python(2 & 3), Ruby and many more

=item * Install programming languages locally (per user, under $HOME, no sudo)

=item * Install multiple runtimes (versions) of each programming language

=over

=item * Use fast binary installs where possible

=back

=item * Switch between language runtimes easily

=item * Use specific language runtimes, per project (per directory)

=item * Install packages (gems, modules, libraries) per language/runtime

=item * Install pkgsets (named sets of packages)

=item * Switch to specific pkgsets, per project

=item * Install plugins. Pluggable language and feature support

=item * Run a single command in a specific environment

=back

In other words, for a given directory (and all directories below it) use specific runtimes of the programming languages you need, and make specific packages available to each programming language.

Lola is written for developers, so it not only supports multiple languages, but also multiple sets of installed packages (libraries, modules, gems, etc). So, for example, you can test your Ruby code not only against multiple C binaries, but also against certain sets of installed gems. Lola has special versions of each language's package installer tool, so that packages can be easily installed into your current environment.

If your project uses more than one language, Lola is the perfect tool for setting up your test environments. It keeps its settings in directories called C<.lola/>. Each of these contains the current language settings, and the available package installations, for code run in or below that directory. You can have many of these directories as you want.

Lola can easily script out test scenarios:

for v in 1.8 1.9 2.0; do
  for p in A B C; do
    lola run rb=$v@$p ruby test.rb
  done
done

=head1 Installation

Installing Lola is just getting the Lola source code, putting it somewhere, and then telling your shell where it is. For example:

git clone git@github.com:acmeism/lola ~/src/lola

Then simply add the C and C directories to your PATH and MANPATH:

export PATH=/path/to/lola/bin:"$PATH"
export MANPATH=/path/to/lola/man:"$MANPATH"

All your languages and packages get installed in the directory in the LOLA_ROOT variable. The default is LOLA_ROOT=~/.lola but you can override it, by using a startup line like this:

LOLA_ROOT=/path/lola/root . ~/src/lola/bin/lola-init

Warning: Once you start installing languages, you may not be able to easily move the LOLA_ROOT directory. This is because many languages build binaries that are targeted at their install location. See Configuration below.

=head1 Prerequisites

=over

=item Bash 3.2 (or higher)

Lola is written entirely in Bash, and uses C</bin/bash> (since it manages local Bash versions too). Modern Bash is 4.2+ but MacOSX still clings to 3.2 so we use that. Note that although Lola is written in Bash, it still runs fine under other shells like C).

=item C

Whatever system tools the various languages require to compile and install things. (gcc, make, etc).

On Debian systems this is provided by the C package.

=item C or C

For fetching things from the web.

=item C

For syncing files.

=item C

Used to install Lola and Lola plugins. Also used to read/write config files.

=back

=head1 Plugin Installation

Most of the functionality of Lola comes from Lola plugins. There are a bunch of plugins that come preinstalled. You can easily find and install new ones too. Plugins can be enabled, disabled and removed too.

lola plugin find        # List all known plugins repo urls
lola plugin add <plugin-git-repo-url>

See Plugin Commands below.

=head1 Upgrading

You can upgrade to the latest versions of Lola and plugins with this command:

lola upgrade

This is effectively the same as:

(
  cd $LOLA_SRC
  git pull origin master
  lola update
)

=head1 Configuration

A Lola setup is based on a few environment variables. The C script used above, sets default values for these (if they are not already set):

=over

=item C<LOLA_SRC>

The source code directory for Lola. If you cloned Lola from GitHub, set this variable to the path of the C git repo.

=item C<LOLA_ROOT>

The directory where all the language specific components live. Since languages get built and installed here, it is very likely that if you move this directory later, things will not work.

=back

=head1 Commands

Lola strives to have simple, intuitive command usage. Tab completion is fully suported. Common command terms have alias symbols. You can even use the C for interactive usage. Or, you can script lola commands with explicit arguments for readability.

=head1 Command options and arguments

The following options and common arguments apply to many commands:

=over

=item C<-q>

Command output should be more quiet.

=item C<-v>

Command output should be more verbose.

=item C<< >>

Language ID. Every supported language has an id (generally 2-4 lowercase chars), like C for Perl. There is a default lid which gets set by certain commands, and you can always override the value for commands that need a lid.

=item C<< >>

This is a tag referring to a specific runtime installation of a specific programming language.

=item C<< >>

A named set of installed/available packages.

=back

=head1 Common Commands

=over

=item C

With no arguments, Lola will run C by default (configurable). The shell will display useful startup info. Press -d to exit.

=item C<lola -? | -h>

Show short help.

=item C

Show the Lola documentation (manpage).

=item C<< lola >>

Same as C<< lola lang ; lola show >>.

=item C<< lola lang >>

Set the default language-id for commands to use.

=item C<< lola show [ ...] >>

Show everything about the current Lola environment. Optionally, you can name specific sections to report on.

=item C<< lola install =[] >>

Install (fetch code and build locally) a specific runtime of a programming language. Remember to use tab completion to see the available options.

=item C<< lola set =[@] [] >>

Use a specific language (and optionally a specific package set). If C<< >> is specified, save the settings in that directory, else modify the current shell.

=back

=head2 Package Set Commands

You can create, manage and use named sets of installed packages.

=over

=item C<< lola pkg add [@] >>

Create a new package set for a specific language installation.

=back

=head2 Less Common Commands

=over

=item C<lola upgrade [ (lola | plugin-name) ...]>

Upgrade Lola components. You can do everything or just specific components.

=item C

Make everything in Lola up-to-date internally. Checks your configuration, and rebuilds anything necessary, including the shim files.

=back

=head1 Plugin Commands

=over

=item C

List the Lola plugins in use.

=item C

List the names, descriptions and urls of all known Lola plugins.

=item C<< lola plugin add >>

Add a Lola plugin.

=item C<< lola enable/disable >>

Enable or disable a given plugin.

=item C<< lola remove >>

Remove a given plugin altogether.

=back

=head1 Config Commands

=over

=item C

Show the current Lola configuration.

=item C

Show the current setting of a config key.

=item C

Set a config key to a value.

=back

=head1 Prior Art

Lola is heavily inspired by many local language installers that came before it, including L, L and L. These tools all have their strengths and weaknesses.

Lola attempts to improve on all of these, and offer the same consistent set of features to all languages at once. Using the simple plugin system, new languages can easily be added.

=head1 See Also

=over

=item * L<Specification|https://github.com/ingydotnet/lola/blob/master/Spec.pod>

=item * Lhttps://github.com/sstephenson/rbenv

=item * Lhttps://github.com/tokuhirom/plenv

=back

=cut