[PATCH 6/6] doc: getting started revamp
Jani Nikula
jani.nikula at intel.com
Fri Jan 11 15:06:03 UTC 2019
Be more helpful, reflect current status.
Signed-off-by: Jani Nikula <jani.nikula at intel.com>
---
The boundary between what's updated and what's old is a bit strong
still...
---
getting-started.rst | 91 +++++++++++++++++++++++++++++++++++++--------
1 file changed, 76 insertions(+), 15 deletions(-)
diff --git a/getting-started.rst b/getting-started.rst
index 5d4ce9c1991e..670aadf162df 100644
--- a/getting-started.rst
+++ b/getting-started.rst
@@ -4,29 +4,90 @@
Getting Started
=================
-For getting started grab the latest dim (drm-intel-maintainer) script from::
+Prerequisites
+-------------
- https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dim
+First, you'll need to decide where you store the repositories dim needs. We'll
+call this directory the ``DIM_PREFIX``. It may be an existing directory you use
+for sources, or a dedicated directory for dim use, for example ``$HOME/src`` or
+``$HOME/linux``.
-There's also a sample config file for ~/.dimrc::
+Your maintainer kernel repository [*]_ needs to be placed there too. We'll call
+this the ``DIM_REPO``. You can have dim create it as a fresh clone of Linus'
+upstream, or you can set it up yourself. It's recommended to keep your
+development repository separate, sandboxed if you will, from the maintainer
+repository.
- https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dimrc.sample
+``dim`` assumes the following directories are placed in ``DIM_PREFIX``:
-Plus, there's bash completion in the same directory if you feel like using that.
-Run::
+ * ``DIM_REPO``
+ * maintainer-tools
+ * drm-tip
+ * drm-rerere
- $ dim help
+.. [*] Maintainer repository is used for brevity throughout; it should be
+ understood as either maintainer or committer repository.
-for tons of details about how this thing works. Also see the git repository
-specific pages for details on the patch merging process for each tree. Adjust
-your .dimrc to match your setup and then run::
+Installation
+------------
- $ dim setup
+Create a dim configuration file ``$HOME/.dimrc`` and set it up according to your
+preferences, for example::
-This will also check out the latest maintainer-tools branches, so please replace
-the dim you just downloaded with a symlink after this step. And by the way, if
-you have improvements for dim, see `contributing
-<dim.html#contributing-bug-reports-and-discussion>`_.
+ DIM_PREFIX=$HOME/linux
+ DIM_REPO=$HOME/src
+
+See the `dimrc.sample`_ for details.
+
+.. _dimrc.sample: https://gitlab.freedesktop.org/drm/maintainer-tools/raw/master/dimrc.sample
+
+For the remainder of this text we'll assume the above variables are set, to make
+the text generic. You can actually do that by sourcing ``$HOME/.dimrc`` to your
+shell, or you can just replace the variables as you see them.
+
+Set up ``DIM_PREFIX``::
+
+ $ mkdir -p $DIM_PREFIX
+
+Clone maintainer-tools::
+
+ $ cd $DIM_PREFIX
+ $ git clone https://gitlab.freedesktop.org/drm/maintainer-tools.git
+
+You'll probably want to either add ``$DIM_PREFIX/maintainer-tools`` to ``PATH``,
+or, for example, add a link ``ln -s $DIM_PREFIX/maintainer-tools/dim
+$HOME/bin/dim`` assuming ``$HOME/bin`` is in ``PATH``.
+
+If you have an existing ``DIM_REPO`` you want to use, or want to set it up
+yourself, do that now. Or you can let dim clone Linus' upstream for you as the
+starting point, effectively::
+
+ $ cd $DIM_PREFIX
+ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git $DIM_REPO
+
+Finish the setup, and have dim create drm-tip and drm-rerere, as well as
+``DIM_REPO``::
+
+ $ dim setup
+
+If you like, you can also set up bash completion for dim by adding something
+like this to your ``.bashrc``::
+
+ # dim completion
+ if [ -f $DIM_PREFIX/maintainer-tools/bash_completion ] && ! shopt -oq posix; then
+ . $DIM_PREFIX/maintainer-tools/bash_completion
+ fi
+
+Running dim without arguments will give you brief usage::
+
+ dim
+
+and the reference man page is available via::
+
+ dim help
+
+usage
+-----
If you have a freedesktop.org account and plan to push things on one of the
drm-xxx repos, you should use the ssh://git.freedesktop.org/git/drm-xxx urls
--
2.20.1
More information about the dim-tools
mailing list