fig 0.1.51 → 0.1.52

data/Changes

@@ -1,7 +1,100 @@
+v0.1.52
+
+  Notice:
+
+  A lot of internal changes have been made to make future changes easier and
+  test coverage is significantly better than it was before.  We believe that we
+  haven't broken anything (other than the purposeful changes below), but due to
+  the scope of the changes, we may have done so.  Please report any problems
+  you run into.
+
+  Backwards incompatibilities:
+
+  - Now requires at least ruby v1.8.7.
+
+  - You can no longer run a command without using "--".  Through an accident of
+    implementation, you previously could do
+
+        fig echo foo
+
+    You are now required to run this as
+
+        fig -- echo foo
+
+  - You can no longer specify multiple --clean or --list-configs options.
+
+  - There was partial support for overridding the local location of a package
+    via a "fig.properties" file in the current directory.  A full
+    implementation of this type of thing may come in the future, but for the
+    time being, in the efforts of making the code clean, this is gone.
+
+  - Development now requires at least rspec 2.8.
+
+  New features:
+
+  - "--list-dependencies" option.  This will list all dependencies a given
+    package has, recursively.
+
+    For example, if you have package A which depends upon packages B and C
+    which both depend upon package D, running
+
+        fig --list-dependencies A/1.2.3
+
+    will give you
+
+        B/2.3.4
+        C/3.4.5
+        D/4.5.6
+
+    If you additionally specify "--list-tree", you'll get a nested dependency
+    tree:
+
+        fig --list-dependencies --list-tree A/1.2.3
+
+        A/1.2.3
+            B/2.3.4
+                D/4.5.6
+            C/3.4.5
+                D/4.5.6
+
+    If you don't specify a package descriptor, but you've got a package.fig
+    file in the current directory with the same dependencies as package A
+    above, you'll get
+
+        fig --list-dependencies --list-tree
+
+        <unpublished>
+            B/2.3.4
+                D/4.5.6
+            C/3.4.5
+                D/4.5.6
+
+    If there are no dependencies, you don't specify "--list-tree", and stdout
+    is connected to a terminal:
+
+        fig --list-dependencies package-with-no-dependencies/1.2.3
+
+        <no dependencies>
+
+    However, if stdout is not connected to a terminal:
+
+        fig --list-dependencies package-with-no-dependencies/1.2.3 | cat
+
+        [no output]
+
+    Additionally, you can specify "--list-all-configs"; this will follow all
+    the configurations in the base package.  Note that this will show multiple
+    versions of the same package if different configurations depend upon
+    different versions.
+
 v0.1.51
 
   - You can now set an environment variable to the empty string with "set".
 
+  - Fix bug with same env variable in both APPEND and RETRIEVE statements,
+    causing Fig to attempt to retrieve libs intended for publish. (The bug
+    was introduced in 0.1.49, in commit aa3f3ab6c7, while fixing another bug).
+
 v0.1.50
 
   - Trying to get releases via rake to work properly for multiple platforms.

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2011, Matthew Foemmel
+Copyright (c) 2009-2012, Matthew Foemmel
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/README.md

@@ -1,23 +1,24 @@
 Description
 ===========
 
-Fig is a utility for configuring environments and managing dependencies across a team of developers.
+Fig is a utility for configuring environments and managing dependencies across
+a team of developers.
 
 An "environment" in fig is a set of environment variables.  A "package" is a
-collection of files, along with some metadata describing which environment variables
-should be modified when the package is included.  For instance, each dependency
-may prepend its corresponding jar to CLASSPATH.  The metadata may also list
-that package's lower-level Fig package dependencies. 
+collection of files, along with some metadata describing which environment
+variables should be modified when the package is included.  For instance, each
+dependency may prepend its corresponding jar to CLASSPATH.  The metadata may
+also list that package's lower-level Fig package dependencies.
 
 Fig recursively builds an environment consisting of package dependencies
 (typically specified via command-line options or a package.fig file), each of
 which as noted above may have its own dependencies, and optionally executes a
 shell command in that environment.  The caller's environment is not affected.
 
-Developers can use package.fig files to specify the list of dependencies to use for
-different tasks. This file will typically be versioned along with the rest of
-the source files, ensuring that all developers on a team are using the same
-environemnts.
+Developers can use package.fig files to specify the list of dependencies to use
+for different tasks. This file will typically be versioned along with the rest
+of the source files, ensuring that all developers on a team are using the same
+environments.
 
 Packages exist in two places: a "local" repository cache in the user's home
 directory--also called the fig-home--and a "remote" repository on a shared
@@ -33,84 +34,85 @@ language agnostic (Java doesn't get preferential treatment), and work with
 executables as well as libraries. And unlike APT, fig is cross platform and
 project-oriented.
 
-Installation
-============
-
-     $ gem install fig
-
-Or, if running Ruby 1.8.x...
-
-     $ gem install fig18
-
 Usage
 =====
 
 Fig recognizes the following options:
 
-### Flags ###
+## Flags ##
 
     -?, -h, --help                   display this help text
     -v, --version                    Print fig version
-    -p, --append VAR=VAL             append (actually, prepend) VAL to environment var VAR, delimited by separator
-        --archive FULLPATH           include FULLPATH archive in package (when using --publish)
-        --clean PKG                  remove package from $FIG_HOME
-    -c, --config CFG                 apply configuration CFG, default is 'default'
-    -d, --debug                      print debug info
-        --file FILE                  read fig file FILE. Use '-' for stdin. See also --no-file
-        --force                      force-overwrite existing version of a package to the remote repo
-    -g, --get VAR                    print value of environment variable VAR
-    -i, --include PKG                include PKG (with any variable prepends) in environment
-        --list                       list packages in $FIG_HOME
-        --list-configs PKG           list configurations in package
+    -g, --get VARIABLE               print value of environment variable VARIABLE
+        --list-local, --list         list packages in $FIG_HOME
+        --list-configs               list configurations
+        --list-dependencies          list package dependencies, recursively
+        --list-variables             list all variables defined/used by package and its dependencies
         --list-remote                list packages in remote repo
-    -l, --login                      login to remote repo as a non-anonymous user
+        --list-tree                  for listings, output a tree instead of a list
+        --list-all-configs           for listings, follow all configurations of the base package
+        --clean                      remove package from $FIG_HOME
+        --publish                    install package in $FIG_HOME and in remote repo
+        --publish-local              install package only in $FIG_HOME
+    -c, --config CONFIG              apply configuration CONFIG, default is "default"
+        --file FILE                  read fig file FILE. Use '-' for stdin. See also --no-file
         --no-file                    ignore package.fig file in current directory
-        --publish PKG                install PKG in $FIG_HOME and in remote repo
-        --publish-local PKG          install package only in $FIG_HOME
-        --resource FULLPATH          include FULLPATH resource in package (when using --publish)
-    -s, --set VAR=VAL                set environment variable VAR to VAL
+    -p, --append VARIABLE=VALUE      append (actually, prepend) VALUE to environment variable VARIABLE, delimited by separator
+    -i, --include DESCRIPTOR         include package/version:config specified in DESCRIPTOR (with any variable prepends) in environment
+    -s, --set VARIABLE=VALUE         set environment variable VARIABLE to VALUE
+        --archive PATH               include PATH archive in package (when using --publish)
+        --resource PATH              include PATH resource in package (when using --publish)
     -u, --update                     check remote repo for updates and download to $FIG_HOME as necessary
     -m, --update-if-missing          check remote repo for updates only if package missing from $FIG_HOME
-        --figrc PATH                 use PATH file as .rc file for Fig
+    -l, --login                      login to remote repo as a non-anonymous user
+        --force                      force-overwrite existing version of a package to the remote repo
+        --figrc PATH                 add PATH to configuration used for Fig
         --no-figrc                   ignore ~/.figrc
         --log-config PATH            use PATH file as configuration for Log4r
         --log-level LEVEL            set logging level to LEVEL
                                        (off, fatal, error, warn, info, debug, all)
+        --                           end of fig options; anything after this is used as a command to run
+
+Some of these options may also be expressed as statements in a package.fig
+file.  For instance, `--append`, `--archive`, `--resource`, `include`.
+
+One point of frequent confusion revolves around which statements are concerned
+with publishing packages, and which are for downloading packages and otherwise
+modifying the Fig environment.  The same Fig file can contain both publish
+(e.g., `append`, `resource`) and download (e.g., `include`) statements, but you
+may not want to use the same dependency file for both publishing a package and
+specifying that same package's dependencies, since for example its "build-time"
+dependencies may differ from its "include-time" dependencies.  Multiple config
+sections may be helpful in organizing these concerns.
+
+## Environment Variables Influencing Fig's Behavior ##
+
+    FIG_FTP_THREADS     Optional - Size of FTP session pool. Defaults to 16.
+    FIG_HOME            Optional - Location of local repo cache. Defaults to $HOME/.fighome.
+    FIG_REMOTE_LOGIN    Required for --login, unless $HOME/.netrc is configured.
+    FIG_REMOTE_URL      Require for operations involving the remote repository.
+    FIG_REMOTE_USER     Required for --login, unless $HOME/.netrc is configured.
 
-    --  end of fig options; everything following is a command to run in the fig environment.
-
-Some of these options may also be expressed as statements in a package.fig file.  For instance,
-`--append`, `--archive`, `--resource`, `include`.
-
-One point of frequent confusion revolves around which statements are concerned with publishing packages, and
-which are for downloading packages and otherwise modifying the Fig environment.  The same Fig file
-can contain both publish (e.g., `append`, `resource`) and download (e.g., `include`) statements,
-but you may not want to use the same
-dependency file for both publishing a package and specifying that same package's dependencies,
-since for example its "build-time" dependencies may differ from its "include-time" dependencies.
-Multiple config sections may be helpful in organizing these concerns.
-
-### Environment Variables Influencing Fig's Behavior ###
-
-    `FIG_FTP_THREADS`     Optional - Size of FTP session pool. Defaults to 16.
-    `FIG_HOME`            Optional - Location of local repo cache. Defaults to $HOME/.fighome.
-    `FIG_REMOTE_LOGIN`    Required for --login, unless $HOME/.netrc is configured.
-    `FIG_REMOTE_URL`      Require for operations involving the remote repository.
-    `FIG_REMOTE_USER`     Required for --login, unless $HOME/.netrc is configured.
-
-[--list-remote] When using the `--list-remote` command against an FTP server, fig uses a pool of FTP sessions to improve
- performance. By default it opens 16 connections, but that number can be overridden by setting the
- `FIG_FTP_THREADS` environment variable.
-
-[--login]   If the `--login` option is supplied, fig will look for credentials.  If
- environment variables `FIG_REMOTE_USER` and/or `FIG_REMOTE_PASSWORD` are
- defined, fig will use them instead of prompting the user.  If ~/.netrc exists,
- with an entry corresponding to the host parsed from `FIG_REMOTE_URL`, that
- entry will take precedence over `FIG_REMOTE_USER` and `FIG_REMOTE_PASSWORD`.
- If sufficient credentials are still not found, fig will prompt for whatever is
- still missing, and use the accumulated credentials to authenticate against the
- remote server.  Even if both environment variables are defined, fig will only
- use them if `--login` is given.
+## Commands affected by environment variables
+
+#### `--list-remote` ####
+
+When using the `--list-remote` command against an FTP server, fig uses a pool
+of FTP sessions to improve performance. By default it opens 16 connections, but
+that number can be overridden by setting the `FIG_FTP_THREADS` environment
+variable.
+
+#### `--login` ####
+
+If the `--login` option is supplied, fig will look for credentials.  If
+environment variables `FIG_REMOTE_USER` and/or `FIG_REMOTE_PASSWORD` are
+defined, fig will use them instead of prompting the user.  If ~/.netrc exists,
+with an entry corresponding to the host parsed from `FIG_REMOTE_URL`, that
+entry will take precedence over `FIG_REMOTE_USER` and `FIG_REMOTE_PASSWORD`.
+If sufficient credentials are still not found, fig will prompt for whatever is
+still missing, and use the accumulated credentials to authenticate against the
+remote server.  Even if both environment variables are defined, fig will only
+use them if `--login` is given.
 
 Examples
 ========
@@ -121,7 +123,7 @@ Fig lets you configure environments three different ways:
 * From a "package.fig" file in the current directory
 * From packages included indirectly via one of the previous two methods
 
-### Command Line ###
+## Command Line ##
 
 To get started, let's define an environment variable via the command line and
 execute a command in the new environment. We'll set the "GREETING" variable to
@@ -135,7 +137,11 @@ Also note that when running fig, the original environment isn't affected:
      $ echo $GREETING
      <nothing>
 
-Fig also lets you append environment variables using the system-specified path separator (e.g. colon on unix, semicolon on windows). This is useful for adding directories to the PATH, LD_LIBRARY_PATH, CLASSPATH, etc. For example, let's create a "bin" directory, add a shell script to it, then include it in the PATH:
+Fig also lets you append environment variables using the system-specified path
+separator (e.g. colon on Unix, semicolon on windows). This is useful for adding
+directories to the PATH, LD_LIBRARY_PATH, CLASSPATH, etc. For example, let's
+create a "bin" directory, add a shell script to it, then include it in the
+PATH:
 
     $ mkdir bin
     $ echo 'echo $GREETING, World' > bin/hello
@@ -143,9 +149,11 @@ Fig also lets you append environment variables using the system-specified path s
     $ fig -s GREETING=Hello -p PATH=bin -- hello
     Hello, World
 
-### Fig Files ###
+## Fig Files ##
+
+You can also specify environment modifiers in files. Fig looks for a file
+called "package.fig" in the current directory and automatically processes it.
 
-You can also specify environment modifiers in files. Fig looks for a file called "package.fig" in the current directory and automatically processes it.
 This "package.fig" file implements the previous example:
 
     config default
@@ -158,12 +166,12 @@ Then we can just run:
     $ fig -- hello
     Hello, World
 
-NOTE: The '@' symbol in a given package.fig file (or in a published dependency's .fig
-file) represents the full path to that file's directory.  The 
-above example would
-still work if we just used "bin", but later on when we publish our project to
-the shared repository we'll definitely need the '@', since the project directories will
-live in the fig-home rather than under our current directory).
+NOTE: The '@' symbol in a given package.fig file (or in a published
+dependency's .fig file) represents the full path to that file's directory.  The
+above example would still work if we just used "bin", but later on when we
+publish our project to the shared repository we'll definitely need the '@',
+since the project directories will live in the fig-home rather than under our
+current directory).
 
 A single fig file may have multiple configurations:
 
@@ -177,14 +185,15 @@ A single fig file may have multiple configurations:
       append PATH=@/bin
     end
 
-### Config Sections ###
+## Config Sections ##
 
 Configurations other than "default" can be specified using the "-c" option:
 
     $ fig -c french -- hello
     Bonjour, World
 
-A config section can be included in another config section:
+The statements from one config section can be incorporated into another config
+section via an `include` statement:
 
     config default
       include :spanish
@@ -195,7 +204,15 @@ A config section can be included in another config section:
       append PATH=@/bin
     end
 
-### Packages ###
+Note that config statements cannot be nested within a fig file.  I.e. the
+following is _invalid_:
+
+    config foo
+      config bar
+      end
+    end
+
+## Packages ##
 
 Let's share our little script with the rest of the team by bundling it into a
 package and publishing it. First, point the `FIG_REMOTE_URL` environment
@@ -204,17 +221,20 @@ you can have it point to a local directory:
 
     $ export FIG_REMOTE_URL=file://$(pwd)/remote
 
-Before we publish our package, we'll need to tell fig which files we want to include. We do this by using the "resource" statement in our "package.fig" file:
+Before we publish our package, we'll need to tell fig which files we want to
+include. We do this by using the "resource" statement in our "package.fig"
+file:
 
     resource bin/hello
 
     config default...
 
-Now we can share the package with the rest of the team by using the `--publish` option:
+Now we can share the package with the rest of the team by using the `--publish`
+option:
 
     $ fig --publish hello/1.0.0
 
-Once the package has been published, we can include it in other environments 
+Once the package has been published, we can include it in other environments
 with the `-i` or `--include` option.  (For the purpose of this example, let's
 first move the "package.fig" file out of the way, so that it doesn't confuse
 fig or us.) The "hello/1.0.0" string represents the name of the package and the
@@ -225,24 +245,29 @@ version number.
     ...downloading files...
     Hello, World
 
-The `-u` (or `--update`) option tells fig to check the remote repository for packages if they aren't already installed locally (fig will never make any network connections unless this option is specified). Once the packages are downloaded, we can run the same command without the `-u` option:
+The `-u` (or `--update`) option tells fig to check the remote repository for
+packages if they aren't already installed locally (fig will never make any
+network connections unless this option is specified). Once the packages are
+downloaded, we can run the same command without the `-u` option:
 
     $ fig -i hello/1.0.0 -- hello
     Hello, World
 
-When including a package, you can specify a particular configuration by appending it to the package name using a colon:
+When including a package, you can specify a particular configuration by
+appending it to the package name using a colon:
 
     $ fig -i hello/1.0.0:french -- hello
     Bonjour, World
 
-### Retrieves ###
+## Retrieves ##
 
 By default, the resources associated with a package live in the fig home
-directory, which defaults to "$HOME/.fighome". This doesn't always play nicely with
-IDE's however, so fig provides a "retrieve" statement to copy resources from the repository to
-the current directory.
+directory, which defaults to "$HOME/.fighome". This doesn't always play nicely
+with IDE's however, so fig provides a "retrieve" statement to copy resources
+from the repository to the current directory.
 
-For example, let's create a package that contains a library for the "foo" programming language. Define a "package.fig" file:
+For example, let's create a package that contains a library for the "foo"
+programming language. Define a "package.fig" file:
 
     config default
       append FOOPATH=@/lib/hello.foo
@@ -254,15 +279,17 @@ Then:
     $ echo "print 'hello'" > lib/hello.foo
     $ fig --publish hello-lib/3.2.1
 
-Create a new "package.fig" file (first moving to a different directory or deleting the "package.fig" we just used for publishing):
+Create a new "package.fig" file (first moving to a different directory or
+deleting the "package.fig" we just used for publishing):
 
     retrieve FOOPATH->lib/[package]
     config default
       include hello-lib/3.2.1
     end
 
-Upon a `fig --update`, each resource in FOOPATH will be copied into lib/[package], where [package] resolves to the resource's 
-package name (minus the version).
+Upon a `fig --update`, each resource in FOOPATH will be copied into
+lib/[package], where [package] resolves to the resource's package name (minus
+the version).
 
      $ fig -u
      ...downloading...
@@ -270,8 +297,212 @@ package name (minus the version).
      $ cat lib/hello-lib/hello.foo
      print 'hello'
 
-### Building the gem ###
-Use `rake figbuild` instead of `rake build`, due to a glitch with "gem build's" naming of i386 gems as 'x86', which causes problems with a subsequent `gem install fig18` command; it picks the wrong Fig gem to install.
+Package Statement Descriptions
+==============================
+
+## `add` ##
+
+Specifies a value to be appended to a `PATH`-like environment variable, e.g.
+`CLASSPATH` for Java.  Does not include the delimiter within the variable, just
+the component value.
+
+## `append` ##
+
+Synonym for `add`.
+
+## `archive` ##
+
+Specifies an archive file (either a local path or a URL) that is supposed to be
+incorporated into the package.  This is different from a `resource` in that the
+contents will be extracted as part of installation.
+
+## `command` ##
+
+Specifies a default command to be run for a given `config` when no command is
+given on the command-line.
+
+    config default
+      command echo Hello there.
+    end
+
+Cannot be specified outside of a `config` statement.  There may not be multiple
+commands within a given `config`.
+
+## `config` ##
+
+A grouping of statements that specifies what is to be done.  There must either
+be a configuration named "default" or you will always have to specify a
+configuration on the command-line.
+
+May not be nested.  If you wish to incorporate the effects of one configuration
+into another, use an `include` statement.
+
+## `include` ##
+
+Can be used in two ways: to affect configurations and to declare package
+dependencies.
+
+### Pull one configuration into another ###
+
+You can get the effects of one configuration in another by using the name of
+the other configuration preceded by a colon:
+
+    config a
+      include :b
+    end
+
+    config b
+      ...
+    end
+
+### Declare a package dependency ###
+
+States that one package should be installed prior to the current one; can
+specify a version.
+
+    config default
+      include somepackage/1.2.3
+    end
+
+Dependency version conflicts can be resolved by using `override` clauses.
+
+Say you've got a "base-dependency" package.  Then, in the `package.fig` for
+"middle-dependency-a" you have
+
+    config default
+      include base-dependency/1.2.3
+    end
+
+And in the `package.fig` for "middle-dependency-b" you have
+
+    config default
+      include base-dependency/3.2.1
+    end
+
+Finally, in the `package.fig` for the package you're working on you've got
+
+    config default
+      include middle-dependency-a
+      include middle-dependency-b
+    end
+
+This will produce a conflicting requirement on "base-dependency".  Resolve this
+by either matching the version of one dependency to another:
+
+    config default
+      include middle-dependency-a override base-dependency/3.2.1
+      include middle-dependency-b
+    end
+
+Or specify the same version to both:
+
+    config default
+      include middle-dependency-a override base-dependency/2.2.2
+      include middle-dependency-b override base-dependency/2.2.2
+    end
+
+Multiple `override` clauses can be specified in a single `include` statement.
+
+## `path` ##
+
+Synonym for `add`.
+
+## `resource` ##
+
+Specifies a file (either a local path or a URL) that is supposed to be
+incorporated into the package.  This is different from an `archive` in that the
+contents will not be extracted as part of installation.
+
+## `retrieve` ##
+
+Gives the installation location for a dependency.
+
+## `set` ##
+
+Gives the value of an environment variable.  Unlike `add`/`append`/`path`, this
+is the complete, final value.
+
+Querying Fig Net Effects
+========================
+
+If you've got a long chain of dependencies of packages, it can be challenging
+to figure out the full effects of it.  There are a number of commands for just
+figuring out what things are coming from.
+
+## `--list-dependencies` ##
+
+By itself, this will give you the total set of packages you're pulling in.
+
+For example, if you have package A which depends upon packages B and C
+which both depend upon package D, running
+
+    fig --list-dependencies A/1.2.3
+
+will give you
+
+    B/2.3.4
+    C/3.4.5
+    D/4.5.6
+
+If there are no dependencies and stdout is connected to a terminal you'll get:
+
+    fig --list-dependencies package-with-no-dependencies/1.2.3
+
+    <no dependencies>
+
+However, if stdout is not connected to a terminal:
+
+    fig --list-dependencies package-with-no-dependencies/1.2.3 | cat
+
+    [no output]
+
+### `--list-tree` ###
+
+If you additionally specify `--list-tree`, you'll get a nested dependency
+tree:
+
+    fig --list-dependencies --list-tree A/1.2.3
+
+    A/1.2.3
+        B/2.3.4
+            D/4.5.6
+        C/3.4.5
+            D/4.5.6
+
+If you don't specify a package descriptor, but you've got a package.fig
+file in the current directory with the same dependencies as package A
+above, you'll get
+
+    fig --list-dependencies --list-tree
+
+    <unpublished>
+        B/2.3.4
+            D/4.5.6
+        C/3.4.5
+            D/4.5.6
+
+### `--list-all-configs` ###
+
+This will follow all of the dependencies using all the configurations in the
+package descriptor or the package.fig file.  This will not follow all
+configurations in all depended upon packages, only the ones reachable by one of
+the configurations in the starting package.
+
+Installation and Development
+============================
+
+## Installation ##
+
+    gem install fig
+
+*NOTE*: When installing Fig on Windows you must first have installed the
+Development Kit available from http://rubyinstaller.org/downloads. Instructions
+for installation of the Development Kit are available at
+https://github.com/oneclick/rubyinstaller/wiki/Development-Kit.
+
+## Building the gem ##
+
+    rake build
 
 Community
 =========
@@ -283,4 +514,4 @@ Community
 Copyright
 =========
 
-Copyright (c) 2009-2011 Matthew Foemmel. See LICENSE for details.
+Copyright (c) 2009-2012 Matthew Foemmel. See LICENSE for details.