Emacs interface for GNU Guix

Alex Kost c9aef52121 elisp/ui-package: Add 'guix-package-use-name-at-point' variable 2 years ago
build-aux 2a541005cf build-env.el: Remove unneeded variable 7 years ago
doc 8ce6d219e8 Rename 'guix-search-…' to 'guix-packages-…' commands 3 years ago
elisp c9aef52121 elisp/ui-package: Add 'guix-package-use-name-at-point' variable 2 years ago
images 057e3a61b2 Remove all references to the "GuixSD" name 3 years ago
scheme 057e3a61b2 Remove all references to the "GuixSD" name 3 years ago
.gitignore a2723db920 build: Add target to build "html" documentation 7 years ago
COPYING a0858e50ab Initial commit 9 years ago
INSTALL dbdb8d13e9 Add GNU Build System infrastructure 7 years ago
Makefile.am a2723db920 build: Add target to build "html" documentation 7 years ago
NEWS 13ddadabcd Update NEWS 4 years ago
README 057e3a61b2 Remove all references to the "GuixSD" name 3 years ago
README.org 7e0c4e76b4 Update README 7 years ago
THANKS b94803e8a8 THANKS: Add Oleg and Pierre 5 years ago
autogen.sh dbdb8d13e9 Add GNU Build System infrastructure 7 years ago
configure.ac 4ae8d61c3c build: Support Guile 3.0 4 years ago
guix.scm f764641396 guix.scm: Use 'close-pipe' instead of 'close-port' 5 years ago

README

-*- mode: org -*-

* About

=Emacs-Guix= (aka =guix.el=) provides various features and tools
for [[http://www.gnu.org/software/guix/][GNU Guix]] package manager.

It allows you to manage your Guix profile(s) from Emacs: to install,
upgrade and remove packages, to switch and remove profile generations,
to display all available info about packages and to do many other
things.

If you are [[https://github.com/emacs-evil/evil][Evil]] user, note that [[https://github.com/emacs-evil/evil-collection][Evil Collection]] provide key bindings for
Emacs-Guix.

This README provides only a basic overview on Emacs-Guix, for a full and
detailed description, see the [[https://emacs-guix.gitlab.io/website/manual/latest/html_node/index.html][info manual]] that comes with it.

In short, Emacs-Guix provides the following features:

- Interface for:

+ profiles

+ profile generations (including system generations for Guix System)

+ packages

+ services

+ package licenses

+ package and service locations

+ [[/gnu/store]] items

- Magit-like popup interface for all Emacs-Guix and Guix shell commands
(=M-x guix=).

- Modes to view logs of package builds (=guix-build-log-mode= and
=guix-build-log-minor-mode=).

- Minor mode to "prettify" store file names (to replace hash parts with
"…").

- Shell completions for all guix commands and options (for =M-x shell=
and =M-x eshell=).

- Minor mode with additional functionality for =scheme-mode= to work
with Guix .scm files, particularly with package modules
(=guix-devel-mode=).

On the following screenshot you can see one of the mentioned features,
namely: "list" and "info" interface for Guix packages (this screenshot
was made for an early version of Emacs-Guix, the interface has slightly
changed since then).

[[http://i.imgur.com/gRcu14n.png]]

([[https://gitlab.com/alezost-emacs/alect-themes][alect-light]] theme is used there).

* Installation

Emacs-Guix can be installed using Guix, from [[http://melpa.org/][MELPA]], or it can be used
from a git checkout. *Note* that it is not recommended to mix several
installations (in particular, Guix and MELPA), as it may lead to
incompatibilities in the source (=.scm=) and compiled (=.go=) Guile
files (see [[https://github.com/alezost/guix.el/issues/21][issue 21]]).

** Guix

Just use:

#+BEGIN_SRC sh
guix package -i emacs-guix
#+END_SRC

** MELPA

If you added "melpa" or "melpa-stable" archives to =package-archives= as
it is described on the [[http://melpa.org/#/getting-started][MELPA Getting Started]] page, you can install
"emacs-guix" using =M-x package-install= or =M-x list-packages=
commands.

** Git checkout

Also you can clone this git repository and use Emacs-Guix from this git
checkout (see the info manual for details).

Finally, if you have the git checkout, you can install Guix package for
the current commit of Emacs-Guix using [[file:guix.scm]] file:

#+BEGIN_SRC sh
guix package --install-from-file=guix.scm
#+END_SRC

* IMPORTANT NOTE for non-Guix-System users

If you installed Guix using [[https://www.gnu.org/software/guix/manual/en/html_node/Binary-Installation.html][Binary Installation]] method, most likely your
environment (in particular, =GUILE_LOAD_PATH=) does not know where Guile
modules of Guix and its dependencies are placed (they are somewhere in
the store). But these Guile modules are needed for Emacs-Guix, so…

… if (during using Emacs-Guix) you encounter errors about missing
modules, undefined variables, other strange errors from Guile REPL, or
if you see unexpectedly small amount of Guix packages, you may try the
following workaround for this problem:

- Install =guix= and =guile= into your user profile:

#+BEGIN_SRC sh
guix package -i guile guix
#+END_SRC

This guarantees that all Guile modules required by Guix will be
available for external programs (in particular, for Guile and
Emacs-Guix).

- Make sure your system uses Guix environment, i.e., check that your
=~/.bash_profile= contains lines like these:

#+BEGIN_SRC sh
source "$HOME/.guix-profile/etc/profile"
source "$HOME/.config/guix/current/etc/profile"
#+END_SRC

Note, that the "current" profile should be sourced the last. Thus the
latest guix (fetched by =guix pull=) will have a priority.

If you still have a problem after the above steps, feel free to open an
issue about it.

* Usage

=M-x guix= is the entry point for the available features.

You can also call =M-x guix-help= to get a summary of all available
commands. Here is an *incomplete* list of them:

- Show packages and their definitions:

: M-x guix-all-packages
: M-x guix-installed-user-packages
: M-x guix-installed-system-packages
: M-x guix-packages-by-name
: M-x guix-packages-by-license
: M-x guix-packages-by-location
: M-x guix-package-from-file
: M-x guix-search-by-name
: M-x guix-search-by-regexp

: M-x guix-package-locations
: M-x guix-find-package-definition

- Show profiles and profile generations:

: M-x guix-profiles
: M-x guix-generations
: M-x guix-system-generations

- Show services and their definitions:

: M-x guix-all-services
: M-x guix-services-by-name
: M-x guix-services-by-regexp
: M-x guix-services-by-location

: M-x guix-service-locations
: M-x guix-find-service-definition

- Show store items:

: M-x guix-store-live-items
: M-x guix-store-dead-items
: M-x guix-store-failures
: M-x guix-store-item-referrers
: M-x guix-store-item-references
: M-x guix-store-item-requisites
: M-x guix-store-item-derivers

- Show/browse package licenses:

: M-x guix-licenses
: M-x guix-browse-license-url
: M-x guix-find-license-definition

- Magit-like interface:

: M-x guix

- Miscellaneous commands:

: M-x guix-help
: M-x guix-about
: M-x guix-pull
: M-x guix-prettify-mode
: M-x guix-build-log-mode
: M-x guix-devel-mode