Changes between Version 16 and Version 17 of PackageEnvironments

Timestamp:

09/16/12 07:25:08 (8 months ago)

Author:

tibbe

Comment:

--

PackageEnvironments

@@ -243 +243 @@
 
 Cabal-meta combines listing the location of packages with constraints for those packages. It's not clear if that's a good idea. However it does seem like a good idea to be able to have them in the same file at least. Perhaps instead of just allowing `local-repo: ./cabalenv/index.tar` and the links only being mentioned in there, we should allow listing them directly in this file. This would have the limitation that you cannot include whole .cabal files or tarballs by value, but you could still list links to local packages.
+
+== sandbox command ==
+
+
+Sandboxes are created, inspected, modified, and deleted through the
+`cabal sandox` command:
+
+ * `cabal sandbox init` creates a new sandbox.
+
+ * `cabal sandbox delete` deleted the sandbox, including all packages
+   installed in the sandbox (i.e. in `.cabal-sandbox`).
+
+ * `cabal sandbox add-source` adds a source package to the sandbox
+   package database.
+
+ * In the future we might add commands for showing the packages
+   installed in the sandbox, the sandbox location (i.e. directory),
+   etc.
+
+`sandbox init` creates a new sandbox by creating a specially named
+file, `cabal.sandbox.config`, in the root directory of the package.
+This file contains a `local-repo` and a `install-dirs` `prefix` that
+points to the sandbox (i.e. to `.cabal-sandbox/packages` and
+`.cabal-sandbox` respectively). If this file is present, all builds in
+the package's directory will use the sandbox.
+
+The `cabal.sandbox.config` file is not normally edited by users and
+should contain a warning on top of the file saying that it's machine
+generated. If the user wants to add e.g. package constraints she
+should use the (new) `cabal.config` file, which doesn't exist by
+default but can be added to the package's root directory by the user.
+
+By using two different package environment files (both recognized by
+Cabal through their special names) allows us to have one file that the
+user can edit without worrying about the system overwriting any
+changes she made (including comments and whitespace layout).
+
+Even though the `cabal.sandbox.config` file is normally not edited by
+the user we decided to keep it visible (i.e. not in `.cabal-sandbox`)
+so the user can edit it if desired. We can revisit this choice in the
+future if this proves to confuse users.
+
+The config files have the following priorities, from higher to lower:
+
+ 1. `cabal.sandbox.config`
+ 2. `cabal.config`
+ 3. `~/.cabal/config`
+
+Once a sandbox have been created, all cabal commands (e.g. configure,
+build, and install) will make use of it automatically.
+
+Source packages that have been added ("linked") into the sandbox by
+`add-source` are rebuilt (and reconfigured, if needed) and installed
+into the sandbox each time the main package is built. We most likely
+want to optimize this process some time in the future, to avoid
+rebuilding/relinkining when neccesary.