@@ -0,0 +1,99 @@
3+`psc-package` is an executable which helps manage PureScript dependencies via Git. It can be used directly, but it is also designed to be used by external tools.
9+A _package set_ is a mapping from package names to:
11+- the Git repository URL for the package
12+- the Git ref which should be passed to `git clone` to clone the appropriate version (usually a tag name, but a SHA is also valid)
13+- the package's transitive dependencies
15+A package set repository contains a `packages.json` file which contains all mapping information. `psc-package` uses this information to decide which repos need to be cloned.
17+The default package set is [purescript/package-sets](https://github.com/purescript/package-sets), but it is possible to create custom package sets by forking an existing package set or creating a new one from scratch. One benefit of using the default package set is that it is verified by a continuous integration process.
19+## The `psc-package.json` format
21+Here is a simple project configuration:
25+ "name": "my-project",
27+ "source": "https://github.com/purescript/package-sets.git",
37+- The package set to use to resolve dependencies (this corresponds to a branch or tag of the package set source repository)
38+- The package set source repository Git URL (change this if you want to host your own package sets)
39+- Any dependencies of the project, as a list of names of packages from the package set
45+A new package can be created using `psc-package init`. This will:
47+- Create a simple `psc-package.json` file based on the current compiler version
48+- Add the Prelude as a dependency (this can be removed later)
49+- Sync the local package database (under the `.psc-package/` directory) by cloning any necessary repositories.
53+To add a dependency, either:
55+- Use the `install` command, which will update the project configuration automatically, or
56+- Modify the `psc-package.json` file, and sync manually by running the `update` command.
60+Active project dependencies and project source files under `src` can be compiled using the `build` command.
62+This command is provided as a convenience until external tools add support for `psc-package`. It _might_ be removed in future.
64+### Query the local package database
66+The local package database can be queried using the following commands:
68+- `sources` - list source directories for active package versions. This can be useful when building a command for, say, running PSCi.
69+- `dependencies` - list all transitive dependencies
71+### Add a package to the package set
73+Adding your package to the package set means that others can easily install it as a dependency.
75+Please note that your package will be removed from the set if it is not kept up to date. It can be easily re-added later if this happens.
77+Adding a package is a manual process right now. We would like to add commands to make this process simpler, but for now, please follow these steps:
79+- Tag a release of your library
80+- Run the `dependencies` command to get the list of transitive dependencies
81+- Make a pull request on the package set repository (against `master`) to add a new entry to `packages.json`. Use the dependency information above to fill in the fields, and the name of your new tag.
83+Travis will verify your package builds correctly, and then we will try to merge your pull request. Your package will then be available in the next tagged package set.
85+### Update a package in the set
88+- Make a pull request on `master` to modify the tag named in the package set repository.
90+Again, once Travis verifies your change, we will merge it into `master` and your change will be available in the next tag.
94+### Can I add a dependency which is not in the package set?
96+Not right now. We might add this feature in future, but for now, consider either:
98+- Adding your dependency to the package set if possible, or
99+- Creating your own custom package set