-
Notifications
You must be signed in to change notification settings - Fork 10
retrieve
Specifies a subdirectory, relative to the current directory, to copy files to from packages when an environment variable is expanded. The path referred to by the variable will be copied to the indicated directory.
To be clear, this statement does not perform any action on its own. It creates a side-effect on the manipulation of an environment variable.
Note that this statement goes around the major design philosophy of Fig: you shouldn't care where anything is located.
retrieve VARIABLE->some/directory/path
retrieve ANOTHER_VARIABLE->some/[package]/path
Syntactically, this is similar to path statements, with the
use of equals sign replaced with the arrow ("->").
There is no whitespace allowed around the arrow. The allowed characters in the variable name are the alphanumerics plus underscore, similar to most Unix shells. No quoting or escaping of the variable name or arrow is allowed.
In the v0 grammar the value of the retrieve (the right-hand side
of "->") is restricted to alphanumerics, slash, underscore, period, hyphen,
and square brackets.
In the v1 grammar and later, the value has no character restrictions. In terms of standard quoting and escaping, left square bracket is considered a metacharacter.
Regardless of grammar, the value:
-
Should be a directory path (it's going to end up being a directory whether you want it to be or not). The path is relative to the current directory even if it appears to be absolute under normal operating system rules.
-
Is subject to substitution of the package name.
Fig would prefer to keep the files for all dependencies in the local repository and have your code find the actual locations via environment variables. The reason that this kind of statement exists is to support tools that manage their own runtime environments, e.g. IDEs. If you have no need for such programs, then you don't need this kind of statement. If you are in such a situation, you will need to point your program configuration to the correct locations within your project directory and you will want to periodically do:
cd base/directory/for/project
fig --update
For a retrieve to do anything, Fig must be doing an update, i.e. --update or
--update-if-missing was specified on the command-line, and
the --suppress-retrieves option must not have been specified.
Furthermore, the environment variable that it refers to must be manipulated in a way that requires variable expansion.
If nothing uses the environment variable indicated by the statement, the statement will have no effect. So, given a base package like
# No retrieving done.
retrieve CLASSPATH->some/directory/to/copy/jar/files/to
config default
set FOO=BAR
add WHATEVER=some/path
end
no copying will happen because no manipulation of the CLASSPATH environment variable is done.
Even if the variable is referenced, the statement will have no effect if the
variable doesn't require any expansion, which is always the case within an
unnamed package, e.g. a
package.fig file containing:
retrieve CLASSPATH->some/directory/to/copy/jar/files/to
config default
add CLASSPATH=whatever
end
If, however, the base package has a
name (which means that it will have been
published), then retrieval will happen. So, one could have the above
package.fig and do
fig --publish foo/alpha
fig --update-if-missing foo/alpha
and the files will be retrieved.
Only retrieve statements in the base package will have any effect. So, if you have a package "prerequisite" with the following
retrieve CLASSPATH->from-prerequisite
config default
add CLASSPATH=@/whatever
end
and a base package like
config default
include prerequisite/1
end
then no copying will take place despite the CLASSPATH variable being set.
Retrieve processing happens each time a variable is manipulated. Given a published package like
retrieve->[package]/bin
config default
add PATH=@/a
add PATH=@/b
add PATH=@/c
end
running
fig package/version -- whatever
will result in three copy operations. (See retrieve
expansion for what happens with the string "[package]" in
the right-hand side of the retrieve above.)
Look at variable expansion to learn what exactly happens when these statements are processed.