README.org 9.16 KB
Newer Older
Alex Griffin's avatar
Alex Griffin committed
1 2 3 4 5 6 7 8 9 10 11 12 13
#+TITLE: Nonguix

Nonguix is a software repository for the
[[https://www.gnu.org/software/guix/][GNU Guix]] package manager,
which packages some software which cannot be included in the official
distribution for ethical or policy-related reasons.

Please do NOT promote this repository on any official Guix
communication channels, such as their mailing lists or IRC channel, even in
response to support requests!  This is to show respect for the Guix project's
[[http://www.gnu.org/distros/free-system-distribution-guidelines.html][strict policy]]
against recommending nonfree software, and to avoid any unnecessary hostility.

14 15 16 17
Before using this channel, you should understand the implications of using
nonfree software.  Read [[https://www.gnu.org/philosophy/free-sw.en.html][What is free software?]]
for more information.

18 19 20
(Check out the [[https://gitlab.com/guix-gaming-channels][Guix Gaming Channels]]
if you're interested in nonfree games too!)

21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
* Warning

This channel does not endorse any non-free application.
We believe it is non-ethical, harmful to software development and
restricts the users freedom.
See the [[https://www.gnu.org/philosophy/free-sw.en.html][GNU philosophy]] for a more thorough discussion.

Those packages are provided as a last resort, should none of the official Guix
packages work for you.

You should understand the implication of using non-free software.  Some of those
implications include:

- Endorsement of non-free products and the perpetration of a culture of
  restriction on liberties.

- Non-free software cannot (or hardly) be audited: it can potentially spy on
  you, destroy or steal your data.

As a minimal security measure, it's heavily recommended to run any non-free
software inside a container.

Alex Griffin's avatar
Alex Griffin committed
43 44 45 46 47 48 49 50 51
* Installation

Nonguix can be installed as a
[[https://www.gnu.org/software/guix/manual/en/html_node/Channels.html][Guix channel]].
To do so, add it to =~/.config/guix/channels.scm=:

#+BEGIN_SRC scheme
  (cons* (channel
          (name 'nonguix)
52 53 54 55 56 57 58
          (url "https://gitlab.com/nonguix/nonguix")
          ;; Enable signature verification:
          (introduction
           (make-channel-introduction
            "897c1a470da759236cc11798f4e0a5f7d4d59fbc"
            (openpgp-fingerprint
             "2A39 3FFF 68F4 EF7A 3D29  12AF 6F51 20A0 22FB B2D5"))))
Alex Griffin's avatar
Alex Griffin committed
59 60
         %default-channels)
#+END_SRC
61

62 63
Then run =guix pull=.

64 65 66 67 68 69 70 71
* Using Nonfree Firmware and Drivers

To use Guix System with the standard Linux kernel and nonfree firmware, edit
the ~kernel~ and ~firmware~ fields of the ~operating-system~ definition in
=config.scm=:

#+BEGIN_SRC scheme
  ;; Import nonfree linux module.
72 73
  (use-modules (nongnu packages linux)
               (nongnu system linux-initrd))
74 75 76

  (operating-system
    (kernel linux)
77
    (initrd microcode-initrd)
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
    (firmware (list linux-firmware))
    ...
    )
#+END_SRC

If you only need firmware for a specific piece of hardware, you may be able to
save disk space by using a smaller firmware package instead:

#+BEGIN_SRC scheme
  (firmware (cons* iwlwifi-firmware
                   %base-firmware))
#+END_SRC

Then of course, run ~sudo guix system reconfigure /etc/config.scm~ to apply
your configuration.

94 95 96 97 98 99 100 101 102 103
** Installation image

For some hardware the official Guix installation image won't do
(e.g. unsupported wifi).  You can generate an installation image running the
nonfree Linux kernel and nonfree firmware with the following command:

#+begin_src sh
guix system disk-image /path/to/this/channel/nongnu/system/install.scm
#+end_src

104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
Then you can write the generated disk image to a USB thumbdrive with:

#+BEGIN_SRC sh
# NOTE: This example assumes your thumbdrive is recognized by Linux as /dev/sdb.
dd if=/path/to/disk-image of=/dev/sdb bs=4M status=progress oflag=sync
#+END_SRC

The installation media produced by the above method does not automatically
configure your channels specification.  You need to add Nonguix "manually"
into ~/etc/guix/channels.scm~ and then run ~guix pull~ to make Guix aware of
Nonguix scheme libraries. Below is Guile scheme code to include Nonguix in the
channel specification.

#+BEGIN_SRC scheme
(use-modules (ice-9 pretty-print))
(with-output-to-file "/etc/guix/channels.scm"
  (lambda _
    (pretty-print
     '(cons*
       (channel (name 'nonguix)
		(url "https://gitlab.com/nonguix/nonguix"))
       %default-channels))))
#+END_SRC

128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160
** CPU Microcode

CPU microcode updates are nonfree blobs that apply directly to a processor to
patch its behavior, and are therefore not included in upstream GNU Guix.
However, running the latest microcode is important to avoid nasty CPU bugs and
hardware security vulnerabilities.

To enable early loading of CPU microcode, use the ~microcode-initrd~ function
to add the microcode to the Initial RAM Disk.  Most users can simply import
~(nongnu system linux-initrd)~ and add ~(initrd microcode-initrd)~ to their
~operating-system~ definition, as illustrated above.

If you need to customize the ~initrd~ for some reason, you should first
understand the upstream documentation on
[[https://guix.gnu.org/manual/en/html_node/Initial-RAM-Disk.html][Initial RAM Disks]].
~microcode-initrd~ simply wraps another ~initrd~ function, which you can swap
out for your own. For example, this:

#+BEGIN_SRC scheme
  (initrd microcode-initrd)
#+END_SRC

is exactly equivalent to:

#+BEGIN_SRC scheme
  (initrd (lambda (file-systems . rest)
            (apply microcode-initrd file-systems
                   #:initrd base-initrd
                   #:microcode-packages (list amd-microcode
                                              intel-microcode)
                   rest)))
#+END_SRC

161 162 163 164 165 166 167
** Broadcom Wireless

Some Broadcom wireless hardware requires a proprietary kernel module in
addition to firmware. To use such hardware you will also need to add a service
to load that module on boot, and blacklist conflicting kernel modules:

#+BEGIN_SRC scheme
168
  (use-modules (nongnu packages linux))
169 170 171 172 173

  (operating-system
    (kernel linux)
    ;; Blacklist conflicting kernel modules.
    (kernel-arguments '("modprobe.blacklist=b43,b43legacy,ssb,bcm43xx,brcm80211,brcmfmac,brcmsmac,bcma"))
174
    (kernel-loadable-modules (list broadcom-sta))
175 176
    (firmware (cons* broadcom-bt-firmware
                     %base-firmware))
177
    ...)
178 179
#+END_SRC

180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
** Avoiding kernel recompilation

Since prebuilt substitutes are not currently available for Nonguix, you may find
that ~guix system reconfigure~ recompiles the kernel frequently due to version
bumps in the kernel package. An inferior can be used to pin the kernel version
and avoid lengthy rebuilds.

You must pin both Guix and Nonguix, as the Nonguix kernel packages derive from
those in Guix (so changes in either could cause a rebuild). Your preferred kernel
version must be available in both pinned channels.

Consult the output of ~guix system describe~ to get the commits of Guix and
Nonguix for the current generation. Once you have determined the commits to use,
create an inferior in your system configuration file that pins the channels to
them. Then grab the appropriately-versioned Linux package from the inferior to
use as your kernel.

#+BEGIN_SRC scheme
  (use-modules (srfi srfi-1)    ; for `first'
               (guix channels))
  (operating-system
    (kernel
      (let*
        ((channels
          (list (channel
                 (name 'nonguix)
                 (url "https://gitlab.com/nonguix/nonguix")
                 (commit "ff6ca98099c7c90e64256236a49ab21fa96fe11e"))
                (channel
                 (name 'guix)
                 (url "https://git.savannah.gnu.org/git/guix.git")
                 (commit "3be96aa9d93ea760e2d965cb3ef03540f01a0a22"))))
         (inferior
          (inferior-for-channels channels)))
        (first (lookup-inferior-packages inferior "linux" "5.4.21"))))
    ...)
#+END_SRC

218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236
* Contributing

Contributions are welcome!  If there's a package you would like to add, just
fork the repository and create a Merge Request when your package is ready.
Keep in mind:

- Nonguix follows the same
  [[https://www.gnu.org/software/guix/manual/en/html_node/Coding-Style.html][coding style]]
  as GNU Guix.  If you don't use Emacs, you should make use of the indent
  script from the GNU Guix repository (=./etc/indent-code.el=).
- Commit messages should follow the same
  [[https://www.gnu.org/prep/standards/html_node/Change-Logs.html][conventions]]
  set by GNU Guix.
- Although licensing restrictions are relaxed, packages should still have
  accurate license metadata.
- If a package could be added to upstream GNU Guix with a reasonable amount of
  effort, then it probably doesn't belong in Nonguix.  This isn't a dumping
  ground for subpar packages, but sometimes we may accept free software
  packages which are currently too cumbersome to properly build from source.
237 238
- If your package is a game, you should submit it to the
  [[https://gitlab.com/guix-gaming-channels][Guix Gaming Channels]] instead.
239 240 241 242 243

If you have a history of making quality contributions to GNU Guix or Nonguix
and would like commit access, just ask!  Nontrivial changes should still go
through a simple Merge Request and code review process, but Nonguix needs more
people involved to succeed as a community project.
Ambrevar's avatar
Ambrevar committed
244 245 246 247

* Community

If you want to discuss Nonguix-related topics, you can hang out and stay in
248
touch on the =#nonguix= IRC channel on Freenode.