[bug#54199] [PATCH] doc: Add 'Working on Shepherd' section.

[pelzflorian (Florian Pelz)]

Thank you Attila.

On Mon, Feb 28, 2022 at 07:51:16PM +0100, Attila Lendvai wrote:
> +@item @emph{The Shepherd API}
> +The Scheme code of Shepherd, which is a dependency of certain packages
> +and the Guix codebase itself.  A typical example of this is the Scheme
> +code implementing a Guix System service, e.g. the OpenSSH server service
> +(see @code{openssh-shepherd-service}).

The last line reads like a @ref clickable link.


> +To modify and use a new Shepherd API, you can change the @code{source}
> +and @code{version} field of the @code{shepherd} package in
> +@file{gnu/packages/admin.scm} along these lines:
> +
> +@lisp
> +(define-public shepherd     ; do not change this
> +  (package
> +    (name "shepherd")
> +    (version "dev")
> +    (source (git-checkout
> +             (url "file:///my/path/shepherd/")
> +             (commit "[a commit hash]")))
> +    ...
> +    ))
> +@end lisp
> +
> +To avoid excessive recompilation times, we pick a specific commit in the
> +latter, and only update it as needed.  But the former will pick up any
> +newly recorded commit when we issue a @command{guix system vm
> +/path/to/my-test.scm}.

Don’t you need to update the sha256 hash so Guix picks up that it
needs to rebuild shepherd?  Unless you change the version each time to
a new value.

I wonder if you can just graft, i.e. introduce a
(replacement my-shepherd) field in the

(define-public shepherd     ; do not change this
  (package
    (name "shepherd")
    (replacement my-shepherd)
    …

I have not tested and grafting may be unreliable.

Regards,
Florian