[PATCH 0/1] "Getting Started" section for the manual

DoneSubmitted by Ludovic Courtès.
4 participants
  • Leo Famulari
  • Ludovic Courtès
  • Mathieu Othacehe
  • zimoun
Ludovic Courtès wrote on 31 Aug 2020 22:47
(address . guix-patches@gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
Hi Guix!
Earlier today, a colleague of mine said they were giving Guix“a second chance” after an unsatisfying first attempt. They hadsuccessfully installed it, asked me about “that locale messagefrom ‘guile’” and what’s going on with PATH and all, and told methey’d looked for “getting started” kind of material and didn’tfind any.
Indeed, a search for “guix getting started” in popular search enginesyields nothing really useful. (I know we have getting-started videoson the front page, but for some reason they must not be that easy tofind?)
Anyway, it bothered me that the first-time user experience couldbe this bad, so I wrote this section for the manual. It’s designedto take at most 5mn to read and to have prominent boxes with commandsto paste in a terminal. Perhaps it’s still even too long.
What do you think, comrades?
Ludovic Courtès (1): doc: Add "Getting Started" section.
doc/guix.texi | 214 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 213 insertions(+), 1 deletion(-)
-- 2.28.0
Ludovic Courtès wrote on 31 Aug 2020 22:57
[PATCH 1/1] doc: Add "Getting Started" section.
(address . 43141@debbugs.gnu.org)(name . Ludovic Courtès)(address . ludo@gnu.org)
* doc/guix.texi (Getting Started): New node.(Binary Installation): Refer to it and to "Application Setup".(After System Installation): Refer to "Getting Started".(Features): Add introductory sentence.--- doc/guix.texi | 214 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 213 insertions(+), 1 deletion(-)
Toggle diff (262 lines)diff --git a/doc/guix.texi b/doc/guix.texiindex 6206a93857..5dc30d0cb2 100644--- a/doc/guix.texi+++ b/doc/guix.texi@@ -144,6 +144,7 @@ Project}. * Introduction:: What is Guix about? * Installation:: Installing Guix. * System Installation:: Installing the whole operating system.+* Getting Started:: Your first steps. * Package Management:: Package installation, upgrade, etc. * Development:: Guix-aided software development. * Programming Interface:: Using Guix in Scheme.@@ -196,6 +197,8 @@ System Installation * Installing Guix in a VM:: Guix System playground. * Building the Installation Image:: How this comes to be. +Getting Started+ Manual Installation * Keyboard Layout and Networking and Partitioning:: Initial setup.@@ -562,6 +565,9 @@ wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh chmod +x guix-install.sh ./guix-install.sh @end example++When you're done, @pxref{Application Setup} for extra configuration you+might need, and @ref{Getting Started} for your first steps! @end quotation Installing goes along these lines:@@ -2476,7 +2482,8 @@ as. This means that if you choose to use @command{guix system reconfigure} in root's login shell, you'll need to @command{guix pull} separately. @end quotation -Join us on @code{#guix} on the Freenode IRC network or on+Now, @pxref{Getting Started}, and+join us on @code{#guix} on the Freenode IRC network or on @email{guix-devel@@gnu.org} to share your experience! @@ -2563,6 +2570,207 @@ guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-wit @code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid board, a list of possible boards will be printed. +@c *********************************************************************+@node Getting Started+@chapter Getting Started++Presumably, you've reached this section because either you have+installed Guix on top of another distribution (@pxref{Installation}), or+you've installed the standalone Guix System (@pxref{System+Installation}). It's time for you to get started using Guix and this+section aims to help you do that and give you a feel of what it's like.++Guix is about installing software, so probably the first thing you'll+want to do is to actually look for software. Let's say you're looking+for a text editor, you can run:++@example+guix search text editor+@end example++This command shows you a number of matching @dfn{packages}, each time+showing the package's name, version, a description, and additional info.+Once you've found out the one you want to use, let's say Emacs (ah ha!),+you can go ahead and install it (run this command as a regular user,+@emph{no need for root privileges}!):++@example+guix install emacs+@end example++You've installed your first package, congrats! In the process, you've+probably noticed that Guix downloaded pre-built binaries; or, if you+explicitly chose to @emph{not} use pre-built binaries, then probably+Guix is still building software (@pxref{Substitutes}, for more info).++Unless you're using Guix System, the @command{guix install} command must+have printed this hint:++@example+hint: Consider setting the necessary environment variables by running:++ GUIX_PROFILE="$HOME/.guix-profile"+ . "$GUIX_PROFILE/etc/profile"++Alternately, see `guix package --search-paths -p "$HOME/.guix-profile"'.+@end example++Indeed, you must now tell your shell where @command{emacs} and other+programs installed with Guix are to be found. Pasting the two lines+above will do just that: it will add+@code{$HOME/.guix-profile/bin}---which is where the installed package+is---to the @code{PATH} environment variable. You can paste these two+lines in your shell so they take effect right away, but more importantly+you should add them to @file{~/.bash_profile} (or equivalent file if you+do not use Bash) so that environment variables are set next time you+spawn a shell.++You can go on installing packages at your will. To list installed+packages, run:++@example+guix package --list-installed+@end example++To remove a package, you would unsurprisingly run @command{guix remove}.+A distinguishing feature is the ability to @dfn{roll back} any operation+you made---installation, removal, upgrade---by simply typing:++@example+guix package --roll-back+@end example++This is because each operation is in fact a @dfn{transaction} that+creates a new @dfn{generation}. These generations and the difference+between them can be displayed by running:++@example+guix package --list-generations+@end example++Now you know the basics of package management!++@quotation Going further+@xref{Package Management}, for more about package management. You may+like @dfn{declarative} package management with @command{guix package+--manifest}, managing separate @dfn{profiles} with @option{--profile},+deleting old generations, collecting garbage, and other nifty features+that will come in handy as you become more familiar with Guix. If you+are a developer, @pxref{Development} for additional tools. And if+you're curious, @pxref{Features}, to peek under the hood.+@end quotation++Once you've installed a set of packages, you will want to periodically+@emph{upgrade} them to the latest and greatest version. To do that, you+will first pull the latest revision of Guix and its package collection:++@example+guix pull+@end example++The end result is a new @command{guix} command, under+@file{~/.config/guix/current/bin}. The first time you run @command{guix+pull}, be sure to follow the hint that the command prints and, similar+to what we saw above, paste these two lines in your terminal and+@file{.bash_profile}:++@example+GUIX_PROFILE="$HOME/.config/guix/current/etc/profile"+. "$GUIX_PROFILE/etc/profile"+@end example++@noindent+You must also instruct your shell to point to this new @command{guix}:++@example+hash guix+@end example++At this point, you're running a brand new Guix. You can thus go ahead+and actually upgrade all the packages you previously installed:++@example+guix upgrade+@end example++As you run this command, you will see that binaries are downloaded (or+perhaps some packages are built), and eventually you end up with the+upgraded packages. Should one of these upgraded packages not be to your+liking, remember you can always roll back!++You can display the exact revision of Guix you're currently using by+running:++@example+guix describe+@end example++The information it displays is @emph{all it takes to reproduce the exact+same Guix}, be it at a different point in time or on a different+machine.++@quotation Going further+@xref{Invoking guix pull}, for more information. @xref{Channels}, on+how to specify additional @dfn{channels} to pull packages from, how to+replicate Guix, and more. You may also find @command{time-machine}+handy (@pxref{Invoking guix time-machine}).+@end quotation++If you installed Guix System, one of the first things you'll want to do+is to upgrade your system. Once you've run @command{guix pull} to get+the latest Guix, you upgrade the system like this:++@example+sudo guix system reconfigure /etc/config.scm+@end example++Upon completion, the system runs the latest versions of its software+packages. When you eventually reboot, you'll notice a sub-menu in the+bootloader that reads ``Old system generations'': it's what allows you+to boot @emph{an older generation of your system}, should the latest+generation be ``broken'' or otherwise unsatisfying. Just like for+packages, you can always @emph{roll back} to a previous generation+@emph{of the whole system}:++@example+sudo guix system roll-back+@end example++There are many things you'll probably want to tweak on your system:+adding new user accounts, adding new system services, fiddling with the+configuration of those services, etc. The system configuration is+@emph{entirely} described in the @file{/etc/config.scm} file.+@xref{Using the Configuration System}, to learn how to change it.++Now you know enough to get started!++@quotation Resources+The rest of this manual provides a reference for all things Guix. Here+are some additional resources you may find useful:++@itemize+@item+@xref{Top,,, guix-cookbook, The GNU Guix Cookbook}, for a list of+``how-to'' style of recipes for a variety of applications.++@item+The @uref{https://guix.gnu.org/guix-refcard.pdf, GNU Guix Reference+Card} lists in two pages most of the commands and options you'll ever+need.++@item+The web site contains @uref{https://guix.gnu.org/en/videos/,+instructional videos} covering topics such as everyday use of Guix, how+to get help, and how to become a contributor.++@item+@xref{Documentation}, to learn how to access documentation on your+computer.+@end itemize++We hope you will enjoy Guix as much as the community enjoys building it!+@end quotation+ @c ********************************************************************* @node Package Management @chapter Package Management@@ -2602,6 +2810,10 @@ guix install emacs-guix @node Features @section Features +Here we assume you've already made your first steps with Guix+(@pxref{Getting Started}) and would like to get an overview about what's+going on under the hood.+ When using Guix, each package ends up in the @dfn{package store}, in its own directory---something that resembles @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.-- 2.28.0
Mathieu Othacehe wrote on 1 Sep 2020 20:24
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 43141@debbugs.gnu.org)
Hey Ludo,
This is a really nice addition, I'm sure it will be beneficial forpeople who want to have a first impression of Guix.
Toggle quote (3 lines)> +If you installed Guix System, one of the first things you'll want to do> +is to upgrade your system. Once you've run @command{guix pull} to get> +the latest Guix, you upgrade the system like this:
^ can or may ?
Toggle quote (1 lines)> +The rest of this manual provides a reference for all things Guix. Here
^ provides?
Otherwise, seems great.
Ludovic Courtès wrote on 3 Sep 2020 23:29
(name . Mathieu Othacehe)(address . othacehe@gnu.org)(address . 43141-done@debbugs.gnu.org)
Mathieu Othacehe <othacehe@gnu.org> skribis:
Toggle quote (6 lines)>> +If you installed Guix System, one of the first things you'll want to do>> +is to upgrade your system. Once you've run @command{guix pull} to get>> +the latest Guix, you upgrade the system like this:> ^> can or may ?
Oops, fixed.
Toggle quote (4 lines)>> +The rest of this manual provides a reference for all things Guix. Here> ^> provides?
Unless I’m mistaken, “all things Guix” is a colloquial phrase meaning“all the things related to Guix”.
Pushed as 6a1788e13a3cda09b2a46d3bd909d71297f0b64e.
Thanks for taking a look!
Leo Famulari wrote on 4 Sep 2020 03:15
Re: bug#43141: [PATCH 1/1] doc: Add "Getting Started" section.
On Thu, Sep 03, 2020 at 11:29:35PM +0200, Ludovic Courtès wrote:
Toggle quote (8 lines)> Mathieu Othacehe <othacehe@gnu.org> skribis:> >> +The rest of this manual provides a reference for all things Guix. Here> > ^> > provides?> > Unless I’m mistaken, “all things Guix” is a colloquial phrase meaning> “all the things related to Guix”.
zimoun wrote on 9 Sep 2020 13:53
Re: [bug#43141] [PATCH 0/1] "Getting Started" section for the manual
(name . Ludovic Courtès)(address . ludo@gnu.org)(address . 43141@debbugs.gnu.org)
Hi Ludo,
I am a bit late to the party. :-)
On Mon, 31 Aug 2020 at 22:49, Ludovic Courtès <ludo@gnu.org> wrote:
Toggle quote (2 lines)> What do you think, comrades?
Really nice!

On a side note, let notice that the query "guix search text editor"seems a good example showing some issue with the current 'relevance'scoring.
Toggle snippet (13 lines)guix search text editor | recsel -C -P name | head -10ktexteditoreditorconfig-core-ceditorconfig-vimjava-eclipse-textvimvim-fullpython-editorconfigemacs-editorconfigqemacsne
And for example, the package Emacs is ranked 19th which is not so-muchsatisfactory.
Toggle snippet (15 lines)guix search text editor | recsel -C -P name | grep -n emacs8:emacs-editorconfig9:qemacs18:guile-emacs19:emacs20:emacs-xwidgets21:emacs-wide-int22:emacs-no-x23:emacs-no-x-toolkit24:emacs-next25:emacs-minimal59:emacs-objed63:emacs-nhexl-mode
Well, another story. :-)

Your comment

Commenting via the web interface is currently disabled.

To comment on this conversation send email to 43141@debbugs.gnu.org