[bug#50349] packages: Add 'define-package' syntax.

* guix/packages.scm (define-package): New syntax.
* .dir-locals.el: Add indent rule for 'define-package'.
* etc/indent-code.el (main): Adjust package search regex accordingly.
* etc/snippets/text-mode/guix-commit-message-add-cl-package: Likewise.
* etc/snippets/text-mode/guix-commit-message-add-package: Likewise.
* etc/snippets/text-mode/guix-commit-message-rename-package: Likewise.
* etc/snippets/text-mode/guix-commit-message-update-package: Likewise.
---
Hello Guix,

This patch adds a shorthand for "(define-public name (package ...))":

(define-package my-favorite-package
  (name "my-favorite-package")
  ...)

The purpose is primarily to save the horizontal indent, but IMO it looks
better, and is marginally more clear for newcomers.  I think ideally we could
eventually transition to using this syntax as the primary syntax and only use
'define-public' when necessary.

There are some downsides... it's one more form to keep track of, and 'let'
forms can't easily be used with it.

Since it's a syntax rule, it doesn't cause packages to rebuild (tested). I've
also tested the indentation rules, indent-code.el, and the snippets.

This probably deserves a documentation addition, but I wasn't sure where to
add it without confusing newcomers.  Suggestions welcome!

(If this is accepted, we'll also want to make a few changes to
emacs-guix/elisp/guix-devel.el, adding 'define-package' to
'guix-devel-keywords' and to 'guix-devel-scheme-indent' with level 1.)

What do you all think?
--
Sarah

 .dir-locals.el                                            | 1 +
 etc/indent-code.el                                        | 2 +-
 etc/snippets/text-mode/guix-commit-message-add-cl-package | 2 +-
 etc/snippets/text-mode/guix-commit-message-add-package    | 2 +-
 etc/snippets/text-mode/guix-commit-message-rename-package | 4 ++--
 etc/snippets/text-mode/guix-commit-message-update-package | 2 +-
 guix/packages.scm                                         | 8 ++++++++
 7 files changed, 15 insertions(+), 6 deletions(-)


base-commit: 95c29d2746943733cbe8df7013854d45bb0df413

Hi Sarah,

On Thu, 02 Sep 2021 at 21:06, Sarah Morgensen <iskarian@mgsn.dev> wrote:

> (define-package my-favorite-package
>   (name "my-favorite-package")
>   ...)
>
> The purpose is primarily to save the horizontal indent, but IMO it looks
> better, and is marginally more clear for newcomers.  I think ideally we could
> eventually transition to using this syntax as the primary syntax and only use
> 'define-public' when necessary.

On one hand, I think it is a good idea; especially for newcomers.  On
the other hand, it will break ’git-blame’, isn’t it?

Therefore, I am not convinced such change is worth for ’gnu/packages/’.
Instead it seems worth only for teaching custom packages.  Explaining to
people in my labs, they are often confused between ’define’ and
’define-public’.  But then, there is two “styles” and people could be
more confused.

Well, my feelings are mixed.  Thanks for opening the discussion. :-)


Cheers,
simon

Hi,

zimoun <zimon.toutoune@gmail.com> writes:

> Hi Sarah,
>
> On Thu, 02 Sep 2021 at 21:06, Sarah Morgensen <iskarian@mgsn.dev> wrote:
>
>> (define-package my-favorite-package
>>   (name "my-favorite-package")
>>   ...)
>>
>> The purpose is primarily to save the horizontal indent, but IMO it looks
>> better, and is marginally more clear for newcomers.  I think ideally we could
>> eventually transition to using this syntax as the primary syntax and only use
>> 'define-public' when necessary.
>
> On one hand, I think it is a good idea; especially for newcomers.  On
> the other hand, it will break ’git-blame’, isn’t it?

Yes, there would be a one-time discontinuity.  Reformats like this can
be ignored with the `--ignore-ref' option, or with a file and a config
option:

.git-blame-ignore-revs:
--8<---------------cut here---------------start------------->8---
# Convert 'define-public' forms to 'define-package' forms
15d01b32313f5f2f291b120597719ae92bd26acd
--8<---------------cut here---------------end--------------->8---

.git/config:
--8<---------------cut here---------------start------------->8---
[blame]
        ignoreRevsFile = .git-blame-ignore-revs
--8<---------------cut here---------------end--------------->8---

We could include the latter in e.g. a `.gitconfig' file committed to the
repo, but in order to use config settings from the file, users would
have to first run

  git config --local include.path ../.gitconfig

Thankfully, this only has to be done once per clone.  If you really
wanted to make sure it got run, I suppose you could add it to a 'make'
target.

--
Sarah

Sarah Morgensen schreef op do 02-09-2021 om 21:06 [-0700]:
> Hello Guix,
> 
> This patch adds a shorthand for "(define-public name (package ...))":
> 
> (define-package my-favorite-package
>   (name "my-favorite-package")
>   ...)

This could be even shorter in the special case that the variable name
and package name are the same (modulo types):

(define-package "my-favorite-package"
  (version ...)
  ...)

'datum->syntax' and 'string->symbol' can be used to turn "my-favorite-package"
into an identifier.

A 'define-unexported-package' might be required in some places.

> The purpose is primarily to save the horizontal indent, but IMO it looks
> better, and is marginally more clear for newcomers.  I think ideally we could
> eventually transition to using this syntax as the primary syntax and only use
> 'define-public' when necessary.
> 
> There are some downsides... it's one more form to keep track of, and 'let'
> forms can't easily be used with it.
> 
> Since it's a syntax rule, it doesn't cause packages to rebuild (tested). I've
> also tested the indentation rules, indent-code.el, and the snippets.
> 
> This probably deserves a documentation addition, but I wasn't sure where to
> add it without confusing newcomers.  Suggestions welcome!

‘Defining Packages’ would be a good place I think.

> What do you all think?

This looks nice to me.  IIUC, the define-package is intended to be clearer
to newcomers, so you might want to ask for feedback on the new syntax on
help-guix@gnu.org.

Greetings,
Maxime.