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
