Re: Blog: Guix packaging tutorial

[Ricardo Wurmus]

Hi Pierre,

> Find the last revision attached.  I've taken all comments into
> consideration and I'm quite happy with the result.

I like it!  Thanks for your patience.

Here are some more comments:

* In the section “A "Hello World" package” you use the word
  “commandline”, but it should be “command line”.  (Same in the Scheme
  tutorial and other places throughout.)

* The sentence: “As with the ritualistic "Hello World" taught with most
  programming language, […]” should say “programming languages”.

* I wonder if maybe we should avoid using “guix package” for the first
  example and use “guix build” instead.  The reason is that “guix
  package” might cause additional builds to be performed dependent on
  the state of the user’s default profile (because of profile hooks).
  Using “guix build” bypasses this issue completely.  What do you think?

* Missing period after “(or /s-expression/ in Lisp lingo)”.

* “It can be a literal[…]” –> “An expression can be a literal[…]”,
  because in the previous sentence we used the plural “expressions”.

* “Every function returns the last evaluated expression as value.” –>
  “Every function returns the value of the last evaluated expression.”

* “Use ~let*~ to re-allows the initializers of later variables to refer
  to the earlier variables.” –> “Use ~let*~ to allow later variable
  declarations to refer to earlier definitions.”

* “Create a folder” –> “Create a directory”; “folder” is a GUI metaphor,
  but that’s nitpicking to be fair.  I prefer “directory”, but use
  “folder” if you find it better :)

* “Notice that we have wrapped the package into a ~define-public~
  record” – I would not use the term “record” here, because it could be
  confused with Scheme records.  How about “Note that we have assigned
  the package value to an exported variable name with ~define-public~.”
  You’re saying as much in the following sentence, but I think it would
  be better to avoid the words “warp” and “record” here.

* “$GUIX_CHECKOUT” is not defined anywhere.  You reference it in the
  introduction before telling people to clone the git repository:

   “license :: See =$GUIX_CHECKOUT/guix/licenses.scm= for a full list.”

  I think it would be best to remove any mention of this from the
  introduction.  After telling the readers to “git clone” I think the
  meaning of $GUIX_CHECKOUT would be obvious, but earlier it is not.

* Why use “ruby” as an example after checking out?  Should this be
  mentioned e.g. “Search packages, such as Ruby:” to show that this is
  arbitrary?

* “Let's looks at another” –> “Let's look at another”

* This paragraph is a little difficult to understand for me:

     When downloaded to the store, the source should be different from
     version to version.  Since Git repositories don't contain a
     specific version in their name, we've got to force the download
     folder using ~(file-name (git-file-name name version))~.

  How about this:

     To ensure that the source code from the git repository is stored in
     a unique directory with a readable name we use ~(file-name
     (git-file-name name version))~.

* “Snippets are quoted (i.e. non-evaluated) Scheme code that are a mean
  of patching the source.”  –> “…a means of patching…”

* “native-inputs :: Required for building but not runtime -- installing
                   a package through a substitute won't install these
                   inputs.”

  This is usually true, but the meaning of “native-inputs” is primarily
  important for cross-building packages.  A native input will be used on
  the build machine and should thus be available for the build machine’s
  architecture, not for the target machine.  Since Guix scans for
  references, packages that are only needed at build time will not be
  installed even when they are among the plain “inputs”.  Likewise,
  packages that are in the “native-inputs” may end up leaving a
  reference behind, which will cause them to be downloaded.  (This is
  often a bug, such as in the icedtea packages, which keep unwanted
  references.)

  Not sure if we should change this in the tutorial, because it’s a
  finer point.  The distinction between inputs and propagated-inputs is
  more important and I think it’s done well in your draft.

* “concern to the package, no to the user” –> “…not to the user”

* “The end user can choose” –> I’d prefer just “user” instead of “end
  user”.

* “It's advised to separate outputs only when you've shown it worth:” –>
  “…it’s worth it:”.

* In the configure-flags example I would not use quasiquotation, so
  this:

    #:configure-flags `(,(string-append …

  would become this:

    #:configure-flags (list (string-append …

* “Or from the REPL (assuming the Guix source is in your Guile load
  path):” –> you could remove the assumption by adding an
  add-to-load-path expression to the example.

* “consult the associated functions” –> nitpick: these are “procedures”
  not “functions”.

* The segment starting with “To manipulate the phases,” seems incomplete
  as it does not introduce the “modify-phases” macro itself.

* “this is needed to avoid clashes between, say, the =zlib= variable
  from =licenses.scm= and the =zlib= variable from =compression.scm=.” —
  I suggest adding parenthetical remarks after the modules to clarify
  that these are different types: “(a license value)” and “(a package
  value)”.

* “…process is very similar to the GNU build system but for a few
  specialized arguments.” –> Maybe replace “but” with “except”.e

* “Find more about build systems in…” –> Maybe replace “Find” with
  “Learn” or “Find out”.

* I don’t know if there should be a section “Common pitfalls and best
  practices” other than to point to the checklist in the manual.  If the
  list in the manual misses one of the points I’d rather add them there
  and only link to the list.

* The section on “Recursive importers” does not mention any recursive
  importers :)  How about using the CRAN importer here, which supports
  recursive importing with the “-r” option?

* “All unspecified fields inherit from the parent package” – I think
  “are inherited from” would be better.

* “Sadly some applications can be tough to package” — missing comma
  after “Sadly”.

* I find this sentence a bit confusing: “The GNU build system is the
  flagship of the high-level abstraction layers Guix makes possible to
  build.”  — what does it mean to “build … an abstraction layer”?

Finally, I think the conclusion is a bit anti-climatic :)  I feel like
it misses a sentence after presenting the outlook to the future; maybe
an announcement of a follow-up blog post?  Or encouragement to get
started packaging today?

I’m very happy to see this tutorial so close to being published!  Thanks
again for your efforts!

--
Ricardo