inside the Guile REPL

inside the Guile REPL

[Pjotr Prins]

I have started to document how to use Guix from the Guile REPL.
Tips/hints wanted from experienced hackers! This is not only to keep
my memory fresh, it may be useful for others.

  https://github.com/pjotrp/guix-notes/blob/master/HACKING.org#debugging-the-package

If this is covered elsewhere I would like to know. I find the Guix
documentation itself accurate, but maybe a little terse ;). Using
Org-mode is probably the way to do it, though I find Ludo's work on

  https://en.wikisource.org/wiki/Functional_Package_Management_with_Guix/Build_expressions_and_package_descriptions

to be quite useful.

Pj.

Re: inside the Guile REPL

[Ludovic Courtès]

Pjotr Prins <pjotr.public12@thebird.nl> skribis:

> I have started to document how to use Guix from the Guile REPL.
> Tips/hints wanted from experienced hackers! This is not only to keep
> my memory fresh, it may be useful for others.
>
>   https://github.com/pjotrp/guix-notes/blob/master/HACKING.org#debugging-the-package

Nice work!

I think it would be nice to see what could be folded into the manual.

The “Defining Packages” section attempts to get the reader started with
writing package definitions, also giving references to the various tools
(‘guix import’, ‘guix hash’, etc.)  Do you think there are things that
could be presented differently or added to that section?

The API, things like bags, and using the REPL are largely undocumented
in the manual.  Regarding the REPL, we probably don’t want to duplicate
what’s already in the Guile manual.

However, I agree that giving an example of how to use the REPL
specifically with Guix would be welcome.  Would you like to propose a
patch?  This could be a section below “Defining Packages” with the
transcript of a simple REPL session and cross-references to the relevant
parts of the Guile manual.

The part about patches should be mostly covered by the new “Submitting
Patches” section of the manual, but again, improvements are always
welcome!

Thanks,
Ludo’.

Re: inside the Guile REPL

[Amirouche Boubekki]

On 2015-06-16 09:04, Pjotr Prins wrote:
> I have started to document how to use Guix from the Guile REPL.
> Tips/hints wanted from experienced hackers! This is not only to keep
> my memory fresh, it may be useful for others.
> 
> 
> https://github.com/pjotrp/guix-notes/blob/master/HACKING.org#debugging-the-package
> 
> If this is covered elsewhere I would like to know. I find the Guix
> documentation itself accurate, but maybe a little terse ;). Using
> Org-mode is probably the way to do it, though I find Ludo's work on
> 
> 
> https://en.wikisource.org/wiki/Functional_Package_Management_with_Guix/Build_expressions_and_package_descriptions
> 
> to be quite useful.

Both resource are super useful. Thanks both of you.

> Pj.

-- 
Amirouche ~ amz3 ~ http://www.hyperdev.fr

Re: inside the Guile REPL

[Pjotr Prins]

On Tue, Jun 16, 2015 at 01:38:18PM +0200, Ludovic Courtès wrote:
> I think it would be nice to see what could be folded into the manual.

Let me continue for a while. I am writing up what I am discovering -
and I am enjoying it. Every time I am confirmed that using Guile was a
smart move. I'll try and do it in such a way that it is something of a
tutorial.

In one or two months we can cherry-pick what is there and we can fold
the useful parts into the main Guix docs. 

Pj.

Re: inside the Guile REPL

[Mark H Weaver]

Pjotr Prins <pjotr.public12@thebird.nl> writes:

> I have started to document how to use Guix from the Guile REPL.
> Tips/hints wanted from experienced hackers! This is not only to keep
> my memory fresh, it may be useful for others.
>
>   https://github.com/pjotrp/guix-notes/blob/master/HACKING.org#debugging-the-package

I have a few comments and corrections to offer:

* Several of the code examples have extra close parens at the end which
  are highlighted in red when viewing in a web browser.

* In the Scheme world, we prefer to use the word "procedure" instead of
  "function", to reflect the fact that it is not merely a mapping from
  inputs to outputs but can perform side effects as well.

* In "Hash colon (#:) notation", you write "The #: signifies a symbol or
  literal keyword syntax [...]".  Keywords are distinct from symbols, so
  you shouldn't say it's a symbol.

* In "Percentage (%) notation", it would be good to mention that it is
  merely a convention, like '_' in C.  Scheme treats '%' exactly the
  same as any other letter.

* In "Key-values":
   * 'build-system' is not a method, but rather a record constructor.
   * 'name', 'description', and 'lower' are not functions but rather
     field names.

* In "Defining a function", it might be worth mentioning that 'define'
  can be used to bind identifiers to any value, not just procedures.
  Most prominently, we use it to define packages, build systems, etc.

* In "Defining a variable":
   * 'let' and 'let*' are not functions, but rather special forms.
   * Regarding the difference between 'let' and 'let*', what you wrote
     is true, but the more important difference between let and let* is
     that let* allows the initializers of later variables to refer to
     the earlier variables, whereas the initializers of let only see
     variables outside of the let.  For example:

      (let ((a 1) (b 2))
        (let ((b a) (a b))
          (list a b)))

     returns (2 1), but if the inner let is replaced with let*, then it
     will return (1 1).

* In "Inside functions", you write "Backquote is like quote, but only
  selected subexpressions are evaluated".  This would seem to suggest
  that 'quote' evaluates all subexpressions.  Removing the word "only"
  might help.  Also, the actual name for this construct is 'quasiquote',
  and it might be good to use that name since it is what can be found in
  the Guile manual and on the web.

  Also, You assume the reader knows the shorthand forms of how 'quote'
  and 'quasiquote' are normally written.  The comma is also a shorthand
  for 'unquote', and it would be good to mention that, since it's a good
  name for it and may aid understanding.  It would also be good if the
  first example showed the outer quasiquote, since unquote is not valid
  outside of quasiquote.  ",@" is shorthand for unquote-splicing.

* In "More about Guile/scheme", I don't think it's accurate to say that
  Guile is a "minimalistic" implementation.  It's moderately large for a
  Scheme implementation.

* In "Renaming and moving files", it would be good to show the newer
  'modify-phases' syntax instead.

* In "Starting the daemon", it might be worth mentioning that it should
  be run as root, but that the actual build processes are run as
  unprivileged build users.

* In "From the command line", you gave a suggested command:

    ./pre-inst-env guix --load-path ./gnu

  I'm not sure what you're trying to do there.  When I run that command,
  it says "unrecognized option '--load-path'".  Maybe you meant
  something like this:

    ./pre-inst-env guix package --load-path=./gnu [...]

  but that's not right either, because the <DIR> passed to --load-path
  should be such that module (gnu packages foo) is located in
  <DIR>/gnu/packages/foo.scm.  Anyway, it's not needed because
  ./pre-inst-env automatically adds the right paths to access the
  packages within ./gnu/packages/*.scm.

That's all for now, I'll try to review the rest later.

Anyway, this is a great start.  Thanks for working on it!

      Mark