[PATCH 6/6] doc: getting started revamp
Daniel Vetter
daniel at ffwll.ch
Fri Jan 11 15:23:49 UTC 2019
On Fri, Jan 11, 2019 at 05:06:03PM +0200, Jani Nikula wrote:
> 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.
I think it'd be good to add:
Note that ``DIM_REPO`` is a relative path and can point to a repository
outside of ``DIM_PREFIX``. This is useful if you want to hide all the dim
checkouts somewhere, while still using your existing main kernel git
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
DIM_REPO is supposed to be a relative path still, right?
> +
> +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
Kinda defeats the auto-setup of DIM_PREFIX we now have in dim :-)
> +
> +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
> +-----
Overall lgtm, Reviewed-by: Daniel Vetter <daniel.vetter at ffwll.ch>
>
> 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
>
> _______________________________________________
> dim-tools mailing list
> dim-tools at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dim-tools
--
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch
More information about the dim-tools
mailing list