summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJoey Hess2015-02-28 14:19:27 -0400
committerJoey Hess2015-02-28 14:19:27 -0400
commit6734d89eb49f20329b1c8d5f84a0c462d12a67cc (patch)
tree6348bf60e29c7602d91b5d02a76ca6a68ed7029c /doc
parentf7a02ae4ff8834a1117639cff6198d9dc05e316f (diff)
add components page
Diffstat (limited to 'doc')
-rw-r--r--doc/README.mdwn4
-rw-r--r--doc/components.mdwn43
-rw-r--r--doc/documentation.mdwn1
3 files changed, 46 insertions, 2 deletions
diff --git a/doc/README.mdwn b/doc/README.mdwn
index 3ced98f6..65d1f285 100644
--- a/doc/README.mdwn
+++ b/doc/README.mdwn
@@ -6,8 +6,8 @@ are satisfied.
Propellor is configured via a git repository, which typically lives
in `~/.propellor/` on your development machine. Propellor clones the
repository to each host it manages, in a
-[secure](http://propellor.branchable.com/security/) way. The git repository
-contains the full source code to Propellor, along with its config file.
+[secure](http://propellor.branchable.com/security/) way. See [[components]]
+for details.
Properties are defined using Haskell. Edit `~/.propellor/config.hs`
to get started. There is fairly complete
diff --git a/doc/components.mdwn b/doc/components.mdwn
new file mode 100644
index 00000000..2c67d9db
--- /dev/null
+++ b/doc/components.mdwn
@@ -0,0 +1,43 @@
+Propellor is a single system, but it's made up of some logically separate
+components.
+
+* Propellor is a Haskell library. The library can be installed
+ [from hackage](http://hackage.haskell.org/package/propellor)
+ in the usual ways. It complies with the
+ [[Haskell Package Version Policy|interface_stability]].
+* `~/.propellor/` is a git repository, which contains at least your
+ `config.hs` file and a cabal file. This gets deployed to each machine
+ you manage with propellor, where it's installed as `/usr/local/propellor/`
+* There can also be a propellor command in your PATH. If you `apt-get
+ install propellor`, you'll get one installed, or `cabal install propellor`
+ will put the command in `~/.cabal/bin/propellor`. This propellor command
+ is just a wrapper; it builds and runs what you have set up in `~/.propellor/`
+
+Typically, the `~/.propellor/` git repository is set up by running the
+propellor command, or by [[cloning propellor|install]]. That makes
+the repository contain the full source code to propellor, including
+the Haskell library.
+
+So if you want to, you can edit any part of Propellor's source code.
+Don't like how a property works, or need to make it more general? Just edit
+then copy in `~/.propellor/src/Propellor/` and it will be used. See
+[[contributing]] if you want to send your improvements back.
+
+All that really needs to be in `~/.propellor/` though, is a `config.hs`
+file, and a cabal file. If you want to set up the repository manually,
+and don't want it to contain propellor's source code, here's a stub cabal
+file to get you started:
+
+<pre>
+Name: foo
+Cabal-Version: >= 1.6
+Build-Type: Simple
+Version: 0
+
+Executable propellor-config
+ Main-Is: config.hs
+ GHC-Options: -Wall -threaded -O0
+ Build-Depends: propellor, base >= 3
+</pre>
+
+See [[haskell_newbie]] for an example config.hs file.
diff --git a/doc/documentation.mdwn b/doc/documentation.mdwn
index 9028dfaa..340eb09f 100644
--- a/doc/documentation.mdwn
+++ b/doc/documentation.mdwn
@@ -6,6 +6,7 @@ Other documentation:
* [[man page|usage]]
* [[Haskell Newbie]]
* [[Centralized Git Repository]]
+* [[Components]]
* [[Contributing]]
* [[Interface Stability]]
* [[Coding Stye]]