Allow remappings to change depending on the context.

docs/layout-of-source-files.rst

@@ -6,6 +6,8 @@ Source files can contain an arbitrary number of contract definitions and include
 
 .. index:: source file, ! import
 
+.. _import:
+
 Importing other Source Files
 ============================
 
@@ -68,15 +70,20 @@ remappings so that e.g. ``github.com/ethereum/dapp-bin/library`` is remapped to
 ``/usr/local/dapp-bin/library`` and the compiler will read the files from there. If
 remapping keys are prefixes of each other, the longest is tried first. This
 allows for a "fallback-remapping" with e.g. ``""`` maps to
-``"/usr/local/include/solidity"``.
+``"/usr/local/include/solidity"``. Furthermore, these remappings can
+depend on the context, which allows you to configure packages to
+import e.g. different versions of a library of the same name.
 
 **solc**:
 
-For solc (the commandline compiler), these remappings are provided as ``key=value``
-arguments, where the ``=value`` part is optional (and defaults to key in that
+For solc (the commandline compiler), these remappings are provided as
+``context:prefix=target`` arguments, where both the ``context:`` and the
+``=target`` parts are optional (where target defaults to prefix in that
 case). All remapping values that are regular files are compiled (including
 their dependencies). This mechanism is completely backwards-compatible (as long
-as no filename contains a =) and thus not a breaking change.
+as no filename contains = or :) and thus not a breaking change. All imports
+in files in or below the directory ``context`` that import a file that
+starts with ``prefix`` are redirected by replacing ``prefix`` by ``target``.
 
 So as an example, if you clone
 ``github.com/ethereum/dapp-bin/`` locally to ``/usr/local/dapp-bin``, you can use
@@ -92,6 +99,19 @@ and then run the compiler as
 
   solc github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ source.sol
 
+As a more complex example, suppose you rely on some module that uses a
+very old version of dapp-bin. That old version of dapp-bin is checked
+out at ``/usr/local/dapp-bin_old``, then you can use 
+
+.. code-block:: bash
+
+  solc module1:github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ \
+       module2:github.com/ethereum/dapp-bin/=/usr/local/dapp-bin_old/ \
+       source.sol
+
+so that all imports in ``module2`` point to the old version but imports
+in ``module1`` get the new version.
+
 Note that solc only allows you to include files from certain directories:
 They have to be in the directory (or subdirectory) of one of the explicitly
 specified source files or in the directory (or subdirectory) of a remapping

docs/miscellaneous.rst

@@ -108,7 +108,7 @@ Using ``solc --help`` provides you with an explanation of all options. The compi
 If you only want to compile a single file, you run it as ``solc --bin sourceFile.sol`` and it will print the binary. Before you deploy your contract, activate the optimizer while compiling using ``solc --optimize --bin sourceFile.sol``. If you want to get some of the more advanced output variants of ``solc``, it is probably better to tell it to output everything to separate files using ``solc -o outputDirectory --bin --ast --asm sourceFile.sol``.
 
 The commandline compiler will automatically read imported files from the filesystem, but
-it is also possible to provide path redirects using ``prefix=path`` in the following way:
+it is also possible to provide path redirects using ``context:prefix=path`` in the following way:
 
 ::
 
@@ -121,6 +121,10 @@ always matches). ``solc`` will not read files from the filesystem that lie outsi
 the remapping targets and outside of the directories where explicitly specified source
 files reside, so things like ``import "/etc/passwd";`` only work if you add ``=/`` as a remapping.
 
+You can restrict remappings to only certain source files by prefixing a context.
+
+The section on :ref:`import` provides more details on remappings.
+
 If there are multiple matches due to remappings, the one with the longest common prefix is selected.
 
 If your contracts use :ref:`libraries <libraries>`, you will notice that the bytecode contains substrings of the form ``__LibraryName______``. You can use ``solc`` as a linker meaning that it will insert the library addresses for you at those points: