summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorJoey Hess2016-04-02 15:33:48 -0400
committerJoey Hess2016-04-02 15:33:48 -0400
commitdce7e7bd72fa82ef7461535288b53d89db807566 (patch)
treecf97100b90cddfd988d069059222df4bb8459bc5 /doc
parentbeba93baede04835687e1caeefead24f173d9048 (diff)
parent48608a48bd91743776cf3d4abb2172b806d4b917 (diff)
Merge branch 'joeyconfig'
Diffstat (limited to 'doc')
-rw-r--r--doc/FreeBSD.mdwn6
-rw-r--r--doc/Linux.mdwn2
-rw-r--r--doc/README.mdwn21
-rw-r--r--doc/components.mdwn8
-rw-r--r--doc/forum/upgrading_to_propellor_3.0.mdwn72
-rw-r--r--doc/haskell_newbie.mdwn6
-rw-r--r--doc/todo/chroot_should_type_check_inner_and_outer_OS.mdwn9
-rw-r--r--doc/todo/commandline_to_setup_minimal_repo.mdwn2
-rw-r--r--doc/todo/depend_on_concurrent-output.mdwn3
-rw-r--r--doc/todo/detect_and_use___96__GHC__95__PACKAGE__95__PATH__96__.mdwn6
-rw-r--r--doc/todo/type_level_OS_requirements.mdwn9
-rw-r--r--doc/writing_properties.mdwn10
12 files changed, 120 insertions, 34 deletions
diff --git a/doc/FreeBSD.mdwn b/doc/FreeBSD.mdwn
index 2edff223..47b9c65b 100644
--- a/doc/FreeBSD.mdwn
+++ b/doc/FreeBSD.mdwn
@@ -1,8 +1,10 @@
Propellor is in the early stages of supporting FreeBSD. It should basically
work, and there are some modules with FreeBSD-specific properties.
-However, many other properties assume they're being run on a
-Debian Linux system, and need additional porting to support FreeBSD.
+However, many other properties only work on a Debian Linux system, and need
+additional porting to support FreeBSD. Such properties have types like
+`Property DebianLike`. The type checker will detect and reject attempts
+to combine such properties with `Property FreeBSD`.
[Sample config file](http://git.joeyh.name/?p=propellor.git;a=blob;f=config-freebsd.hs)
which configures a FreeBSD system, as well as a Linux one.
diff --git a/doc/Linux.mdwn b/doc/Linux.mdwn
index 0434d69d..00276f69 100644
--- a/doc/Linux.mdwn
+++ b/doc/Linux.mdwn
@@ -6,4 +6,4 @@ Indeed, Propellor has been ported to [[FreeBSD]] now!
See [[forum/Supported_OS]] for porting tips.
Note that you can run Propellor on a OSX laptop and have it manage Linux
-systems.
+and other systems.
diff --git a/doc/README.mdwn b/doc/README.mdwn
index b17f8575..31d222c1 100644
--- a/doc/README.mdwn
+++ b/doc/README.mdwn
@@ -42,20 +42,15 @@ see [configuration for the Haskell newbie](https://propellor.branchable.com/hask
`cabal install propellor`
or
`apt-get install propellor`
-2. Run `propellor` for the first time. It will set up a `~/.propellor/` git
+2. Run `propellor --init` ; this will set up a `~/.propellor/` git
repository for you.
-3. If you don't have a gpg private key already, generate one: `gpg --gen-key`
-4. Run: `propellor --add-key $KEYID`, which will make propellor trust
- your gpg key, and will sign your `~/.propellor` repository using it.
-5. Edit `~/.propellor/config.hs`, and add a host you want to manage.
+3. Edit `~/.propellor/config.hs`, and add a host you want to manage.
You can start by not adding any properties, or only a few.
-6. Run: `propellor --spin $HOST`
-7. Now you have a simple propellor deployment, but it doesn't do
- much to the host yet, besides installing propellor.
- So, edit `~/.propellor/config.hs` to configure the host, add some
- properties to it, and re-run step 6.
- Repeat until happy and move on to the next host. :)
-8. Once you have a lot of hosts, and running `propellor --spin HOST` for
+4. Run: `propellor --spin $HOST`
+5. Now you have a simple propellor deployment to a host. Continue editing
+ `~/.propellor/config.hs` to further configure the host, add more hosts
+ etc, and re-run `propellor --spin $HOST` after each change.
+6. Once you have a lot of hosts, and running `propellor --spin HOST` for
each host becomes tiresome, you can
[automate that](http://propellor.branchable.com/automated_spins/).
-9. Write some neat new properties and send patches!
+7. Write some neat new properties and send patches!
diff --git a/doc/components.mdwn b/doc/components.mdwn
index 801bb6bf..5b47e106 100644
--- a/doc/components.mdwn
+++ b/doc/components.mdwn
@@ -28,12 +28,8 @@ then copy in `~/.propellor/src/Propellor/` and it will be used. See
## minimal .propellor repository
All that really needs to be in `~/.propellor/` though, is a `config.hs`
-file, and a cabal file. To use propellor this way, you can first
-install propellor, and then copy the two files from the
-[mininalconfig branch](http://source.propellor.branchable.com/?p=source.git;a=tree;h=refs/heads/minimalconfig;hb=refs/heads/minimalconfig),
-or clone it:
-
- git clone git://propellor.branchable.com/ .propellor --branch minimalconfig --single-branch
+file, and a cabal file. Running propellor when `~/.propellor/` doesn't exist
+will ask you if you want a minimal config, and create those files.
In this configuration, when propellor is deploying itself to a new host,
it will automatically install the version of the propellor library
diff --git a/doc/forum/upgrading_to_propellor_3.0.mdwn b/doc/forum/upgrading_to_propellor_3.0.mdwn
new file mode 100644
index 00000000..af54e938
--- /dev/null
+++ b/doc/forum/upgrading_to_propellor_3.0.mdwn
@@ -0,0 +1,72 @@
+Propellor 3.0 is a major new version with large changes to the API.
+
+Property types have been improved to indicate what systems they target.
+This prevents using eg, Property FreeBSD on a Debian system.
+
+This forum topic is to help users with the upgrade. Post comments
+if you're having trouble and [[Joey]] will get back to you. ;)
+
+First things first: In order to upgrade to propellor 3.0, you **must first
+upgrade to propellor 2.17.2**, and deploy that to all your hosts. If you
+skip this step, propellor --spin will fail when you upgrade to propellor
+3.0.0.
+(Workaround: ssh to host, cd /usr/local/propellor && make clean,
+then you can re-run propellor --spin.)
+[[details_of_why_this_two_step_upgrade_is_needed|todo/problem_with_spin_after_new_dependencies_added]]
+
+Now, the transition guide as far as your config.hs goes:
+
+* Change "host name & foo & bar"
+ to "host name $ props & foo & bar"
+* Similarly, `propertyList` and `combineProperties` need `props`
+ to be used to combine together properties; they no longer accept
+ lists of properties. (If you have such a list, use `toProps`.)
+* And similarly, Chroot, Docker, and Systemd container need `props`
+ to be used to combine together the properies used inside them.
+* The `os` property is removed. Instead use `osDebian`, `osBuntish`,
+ or `osFreeBSD`. These tell the type checker the target OS of a host.
+* GHC needs `{-# LANGUAGE TypeOperators #-}` to use these fancy types.
+ This is enabled by default for all modules in propellor.cabal. But
+ if you are using propellor as a library, you may need to enable it
+ manually.
+
+Additional things you need to do if you've written your own properties:
+
+* Change "Property NoInfo" to "Property UnixLike"
+* Change "Property HasInfo" to "Property (HasInfo + UnixLike)"
+* Change "RevertableProperty NoInfo" to
+ "RevertableProperty UnixLike UnixLike"
+* Change "RevertableProperty HasInfo" to
+ "RevertableProperty (HasInfo + UnixLike) UnixLike"
+* If you know a property only works on a particular OS, like Debian
+ or FreeBSD, use that instead of "UnixLike". For example:
+ "Property Debian"
+* It's also possible make a property support a set of OS's, for example:
+ "Property (Debian + FreeBSD)"
+* Removed `infoProperty` and `simpleProperty` constructors, instead use
+ `property` to construct a Property.
+* Due to the polymorphic type returned by `property`, additional type
+ signatures tend to be needed when using it. For example, this will
+ fail to type check, because the type checker cannot guess what type
+ you intend the intermediate property "go" to have:
+ foo :: Property UnixLike
+ foo = go `requires` bar
+ where
+ go = property "foo" (return NoChange)
+ To fix, specify the type of go:
+ go :: Property UnixLike
+* `ensureProperty` now needs to be passed a witness to the type of the
+ property it's used in.
+ change this: foo = property desc $ ... ensureProperty bar
+ to this: foo = property' desc $ \w -> ... ensureProperty w bar
+* General purpose properties like cmdProperty have type "Property UnixLike".
+ When using that to run a command only available on Debian, you can
+ tighten the type to only the OS that your more specific property works on.
+ For example:
+ upgraded :: Property Debian
+ upgraded = tightenTargets (cmdProperty "apt-get" ["upgrade"])
+* Several utility functions have been renamed:
+ getInfo to fromInfo
+ propertyInfo to getInfo
+ propertyDesc to getDesc
+ propertyChildren to getChildren
diff --git a/doc/haskell_newbie.mdwn b/doc/haskell_newbie.mdwn
index e92481f9..bd343cd6 100644
--- a/doc/haskell_newbie.mdwn
+++ b/doc/haskell_newbie.mdwn
@@ -48,12 +48,12 @@ Finally, you need to define the configuration for each host in the list:
[[!format haskell """
mylaptop :: Host
mylaptop = host "mylaptop.example.com"
- & os (System (Debian Unstable) "amd64")
+ & osDebian Unstable "amd64"
& Apt.stdSourcesList
myserver :: Host
myserver = host "server.example.com"
- & os (System (Debian (Stable "jessie")) "amd64")
+ & osDebian (Stable "jessie") "amd64"
& Apt.stdSourcesList
& Apt.installed ["ssh"]
"""]]
@@ -96,7 +96,7 @@ is.
<pre>
config.hs:30:19:
Couldn't match expected type `RevertableProperty'
- with actual type `Property NoInfo'
+ with actual type `Property DebianLike'
In the return type of a call of `Apt.installed'
In the second argument of `(!)', namely `Apt.installed ["ssh"]'
In the first argument of `(&)', namely
diff --git a/doc/todo/chroot_should_type_check_inner_and_outer_OS.mdwn b/doc/todo/chroot_should_type_check_inner_and_outer_OS.mdwn
new file mode 100644
index 00000000..ff5d5434
--- /dev/null
+++ b/doc/todo/chroot_should_type_check_inner_and_outer_OS.mdwn
@@ -0,0 +1,9 @@
+Currently chroot properties containing any OS can be added to any host. Of
+course, some won't work. It would be nice to type check that the
+combination of inner and outer OS are compatable (ie, some linux on some
+linux).
+
+I have a partially done patch for that, but it failed at the last hurdle.
+See commit message 0b0ea182ab3301ade8b87b1be1cdecc3464cd1da
+
+[[!tag users/joey]]
diff --git a/doc/todo/commandline_to_setup_minimal_repo.mdwn b/doc/todo/commandline_to_setup_minimal_repo.mdwn
index 5e82ed0f..2b41d370 100644
--- a/doc/todo/commandline_to_setup_minimal_repo.mdwn
+++ b/doc/todo/commandline_to_setup_minimal_repo.mdwn
@@ -3,3 +3,5 @@ parameters, like --minimal to clone the minimal config repo instead of the
full one, or --stack to set up ~/.propellor to use stack. --[[Joey]]
> Or, it could be an interactive setup process. --[[Joey]]
+
+>> Made it interactive. [[done]] --[[Joey]]
diff --git a/doc/todo/depend_on_concurrent-output.mdwn b/doc/todo/depend_on_concurrent-output.mdwn
index fdc66b04..a104c82b 100644
--- a/doc/todo/depend_on_concurrent-output.mdwn
+++ b/doc/todo/depend_on_concurrent-output.mdwn
@@ -8,3 +8,6 @@ Once this is done, can switch GHC-Options back to -O0 from -O.
-O0 is better because ghc takes less memory to build propellor.
[[!tag user/joey]]
+
+> [[done]]. Didn't wait for it to hit stable; cabal will be used to install
+> it.
diff --git a/doc/todo/detect_and_use___96__GHC__95__PACKAGE__95__PATH__96__.mdwn b/doc/todo/detect_and_use___96__GHC__95__PACKAGE__95__PATH__96__.mdwn
index 2973e662..55c3ef7e 100644
--- a/doc/todo/detect_and_use___96__GHC__95__PACKAGE__95__PATH__96__.mdwn
+++ b/doc/todo/detect_and_use___96__GHC__95__PACKAGE__95__PATH__96__.mdwn
@@ -7,3 +7,9 @@ and run with
stack exec -- propellor ...
see [[https://github.com/yesodweb/yesod/issues/1018]] and [[https://github.com/yesodweb/yesod/commit/a7cccf2a7c5df8b26da9ea4fdcb6bac5ab3a3b75]]
+
+> I don't think `stack exec propellor` makes sense to use.
+> Instead, `stack install propellor` and then put that in PATH.
+> I've now made `propellor --init` know when it was built using stack,
+> and it will set up propellor to continue to build itself using stack.
+> [[done]] --[[Joey]]
diff --git a/doc/todo/type_level_OS_requirements.mdwn b/doc/todo/type_level_OS_requirements.mdwn
index 7c2fb78f..fed1b279 100644
--- a/doc/todo/type_level_OS_requirements.mdwn
+++ b/doc/todo/type_level_OS_requirements.mdwn
@@ -21,13 +21,12 @@ withOS.
The `os` property would need to yield a `Property (os:[])`, where the type
level list contains a type-level eqivilant of the value passed to the
-property. Is that possible to do? reification or something?
-(See: <https://www.schoolofhaskell.com/user/thoughtpolice/using-reflection>)
-Or, alternatively, could have less polymorphic `debian` etc
+property. Is that possible to do?
+Or, alternatively, could have less polymorphic `osDebian` etc
properties replace the `os` property.
If a Host's list of properties, when all combined together,
-contains more than one element in its '[OS], that needs to be a type error,
+contains more than one element in its '[OS], that could be a type error,
the OS of the Host is indeterminite. Which would be fixed by using the `os`
property to specify.
@@ -53,3 +52,5 @@ work with that version, with some added ugliness.
--[[Joey]]
[[!tag user/joey]]
+
+> [[done]]!! --[[Joey]]
diff --git a/doc/writing_properties.mdwn b/doc/writing_properties.mdwn
index 2209026f..1b7f046a 100644
--- a/doc/writing_properties.mdwn
+++ b/doc/writing_properties.mdwn
@@ -31,7 +31,7 @@ Propellor makes it very easy to put together a property like this.
Let's start with a property that combines the two properties you mentioned:
- hasLoginShell :: UserName -> FilePath -> Property
+ hasLoginShell :: UserName -> FilePath -> Property UnixLike
hasLoginShell user shell = shellSetTo user shell `requires` shellEnabled shell
The shellEnabled property can be easily written using propellor's file
@@ -40,14 +40,14 @@ manipulation properties.
-- Need to add an import to the top of the source file.
import qualified Propellor.Property.File as File
- shellEnabled :: FilePath -> Property
+ shellEnabled :: FilePath -> Property UnixLike
shellEnabled shell = "/etc/shells" `File.containsLine` shell
And then, we want to actually change the user's shell. The `chsh(1)`
program can do that, so we can simply tell propellor the command line to
run:
- shellSetTo :: UserName -> FilePath -> Property
+ shellSetTo :: UserName -> FilePath -> Property UnixLike
shellSetTo user shell = cmdProperty "chsh" ["--shell", shell, user]
The only remaining problem with this is that shellSetTo runs chsh every
@@ -56,7 +56,7 @@ it runs, even when it didn't really do much. Now, there's an easy way to
avoid that problem, we could just tell propellor to assume that chsh
has not made a change:
- shellSetTo :: UserName -> FilePath -> Property
+ shellSetTo :: UserName -> FilePath -> Property UnixLike
shellSetTo user shell = cmdProperty "chsh" ["--shell", shell, user]
`assume` NoChange
@@ -64,7 +64,7 @@ But, it's not much harder to do this right. Let's make the property
check if the user's shell is already set to the desired value and avoid
doing anything in that case.
- shellSetTo :: UserName -> FilePath -> Property
+ shellSetTo :: UserName -> FilePath -> Property UnixLike
shellSetTo user shell = check needchangeshell $
cmdProperty "chsh" ["--shell", shell, user]
where