From 19e6d56f977de10b073f1029f4d6c4cbdf1969ad Mon Sep 17 00:00:00 2001
From: Nick Coghlan <ncoghlan@gmail.com>
Date: Nov 02 2017 06:32:12 +0000
Subject: Issue 26: Document --build-deps options


---

diff --git a/README.md b/README.md
index 62e4fe0..9db3fd7 100644
--- a/README.md
+++ b/README.md
@@ -15,24 +15,22 @@ Currently, this consists of:
 
 ## Project status
 
-`fedmod` is not yet released as an RPM, but can already generate basic draft
-modules from a local development checkout:
+`fedmod` is not yet available from the main Fedora repos, but can be installed
+from [COPR](https://copr.fedorainfracloud.org/coprs/g/modularity/fedmod/)
+as follows:
 
-    $ pipenv run fedmod fetch-metadata
-    $ pipenv run fedmod rpm2module graphite-web
-
-This will generate a draft `modulemd` file called `graphite-web.yaml` in the
-current directory.
+    $ sudo dnf copr enable @modularity/fedmod
+    $ sudo dnf install python3-fedmod
+    $ fedmod fetch-metadata
+    $ fedmod rpm2module graphite-web
 
-See the local development instructions below for info on setting up the
-execution environment with `pipenv`.
+This will generate a draft `modulemd` file for Fedora's `graphite-web`
+package on stdout.
 
-Note: while an initial release is available from
-[PyPI](https://pypi.org/project/fedmod/), the dependency on the system level
-`dnf` and `solv` libraries means it can't be usefully installed with `pipsi`
-(as attempting to import those dependencies will fail at runtime).
+See the local development instructions below for info on running directly
+from a local development clone with `pipenv`.
 
-## Interim alternative
+## F27 pre-release alternative
 
 `fedmod` aims to generate draft module definitions based on the same repository
 level metadata that `dnf module` uses to actually install and manage modules.
@@ -57,12 +55,25 @@ whichever one you think looks better as your starting point.
 
 ## Modulemd creation
 
-`fedmod rpm2module [RPM NAMES]` creates a modulemd file from the
-given package names and emits it on `stdout`. The YAML metadata can be written
+Before generating any draft modulemd files, first run the following command to
+fetch and locally cache the required metadata files:
+
+    $ fedmod fetch-metadata
+
+`fedmod rpm2module [RPM NAMES]` will then create a modulemd file from the
+given package names and emit it on `stdout`. The YAML metadata can be written
 directly to a file instead by passing the ``--output` (or `-o`) option:
 
     $ fedmod rpm2module -o graphite-web.yaml graphite-web
 
+Only module level build dependencies are generated by default - there is no
+attempt to make the generated module definition self-hosting. If a self-hosting
+module is desired, then the `--build-deps N` option can be passed, where `N` is
+the number of levels of recursive build dependencies to attempt to include (this
+can quickly become unmanageable due to dependencies on build tools that
+themselves have complex build requirements, but are not yet part of a defined
+module)
+
 The following metadata is currently used as input to the draft module generation
 process:
 
@@ -119,7 +130,6 @@ installed system-wide:
 
     $ sudo dnf install python3-dnf python3-solv
 
-
 ### Additional development dependencies
 
 `pipenv` itself isn't packaged for Fedora yet, so the recommended bootstrapping
@@ -139,6 +149,16 @@ management, `pew`. These can later be updated to newer versions using `pipsi`:
 (Note: the `pipsi list` command will list all packages installed via `pipsi`,
 and the commands they provide)
 
+### Running the development version
+
+After setting up the `pipenv` environment, the development version can be
+run as follows
+
+    $ pipenv run fedmod fetch-metadata
+    $ pipenv run fedmod rpm2module graphite-web
+
+Alternatively, start an interactive shell as described below for running the
+tests, and `fedmod` will refer to the development version.
 
 ### Running the tests