@@ -0,0 +1,99 @@
1+# `psc-package`
2+
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.
4+
5+## Concepts
6+
7+### Package Sets
8+
9+A _package set_ is a mapping from package names to:
10+
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
14+
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.
16+
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.
18+
19+## The `psc-package.json` format
20+
21+Here is a simple project configuration:
22+
23+```json
24+{
25+ "name": "my-project",
26+ "set": "psc-0.10.2",
27+ "source": "https://github.com/purescript/package-sets.git",
28+ "depends": [
29+ "prelude"
30+ ]
31+}
32+```
33+
34+It defines:
35+
36+- The project name
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
40+
41+## How To
42+
43+### Create a project
44+
45+A new package can be created using `psc-package init`. This will:
46+
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.
50+
51+### Add dependencies
52+
53+To add a dependency, either:
54+
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.
57+
58+### Build a project
59+
60+Active project dependencies and project source files under `src` can be compiled using the `build` command.
61+
62+This command is provided as a convenience until external tools add support for `psc-package`. It _might_ be removed in future.
63+
64+### Query the local package database
65+
66+The local package database can be queried using the following commands:
67+
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
70+
71+### Add a package to the package set
72+
73+Adding your package to the package set means that others can easily install it as a dependency.
74+
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.
76+
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:
78+
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.
82+
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.
84+
85+### Update a package in the set
86+
87+- Tag a new release
88+- Make a pull request on `master` to modify the tag named in the package set repository.
89+
90+Again, once Travis verifies your change, we will merge it into `master` and your change will be available in the next tag.
91+
92+## FAQ
93+
94+### Can I add a dependency which is not in the package set?
95+
96+Not right now. We might add this feature in future, but for now, consider either:
97+
98+- Adding your dependency to the package set if possible, or
99+- Creating your own custom package set