• Developer installation with Guix
• Developer installation with Nix
  • Building for local development
  • Compiling
• Standard developer installation
  • Installing SBCL
  • Installing Quicklisp (optional)
  • GTK dependencies
    • Lisp dependencies
    • GNU/Linux, FreeBSD GTK dependencies
    • macOS specific dependencies
  • Qt dependencies
    • Lisp dependencies
    • GNU/Linux, FreeBSD dependencies
    • macOS dependencies
  • Fetch the source code
  • Compile
    • Using the Makefile
    • Using Lisp
  • Update local Lisp libraries
• Run Nyxt in a security sandbox
• Hacking
  • Run from source
  • Interacting with a compiled version of Nyxt
    • SLIME
    • SLY
• Help & Community
  • Learning Common Lisp
  • Contributing
  • IRC Channel

First, clone the Nyxt repository. It is most convenient to clone the Nyxt repository into ~/common-lisp (or another directory where ASDF will find it).

Second, install Guix and follow the instructions in the ../build-scripts/guix.scm file of the Nyxt repository.

To use Nix for local development use the shell.nix file located in the build-scripts directory.

As an example, to run with SBCL, you could do the following: nix-shell nyxt/build-scripts/shell.nix --run sbcl

Then you could use Quicklisp to quickload Nyxt, (ql:quickload :nyxt/gtk-application) (nyxt:start).

To compile the latest Nyxt, from the project root, run the the following:

nix-build -I nixpkgs=channel:nixpkgs-unstable

To compile and install the latest Nyxt, from the project root, run the following:

nix-env -i -f default.nix -I nixpkgs=channel:nixpkgs-unstable

Nyxt is written in Common Lisp. It can be built with any standard Common Lisp implementation. Currently, only SBCL support is tested.

It is designed to be cross-platform, cross-engine compatible. Nyxt is available in both WebKit and WebEngine flavors. Support for graphics and OS integration is provided via:

• macOS: GTK, Qt
• GNU/Linux, FreeBSD: GTK, Qt

You’ll need SBCL ≥ 2.0.0 to compile Nyxt.

You can obtain SBCL from your package manager or by downloading it directly from the SBCL repository.

To install SBCL from source, download SBCL: http://www.sbcl.org/platform-table.html. Full installation instructions can be found here: http://www.sbcl.org/getting.html.

Quicklisp is downloaded and installed automatically by the Makefile. If you wish to install it manually- system-wide- the official Quicklisp website can provide updated links to downloads, and instructions: https://www.quicklisp.org.

To install Quicklisp:

• Download https://beta.quicklisp.org/quicklisp.lisp.
• Execute $LISP --load quicklisp.lisp to load Quicklisp. (Replace $LISP with sbcl or any supported Lisp compiler.)
• Evaluate in the REPL (quicklisp-quickstart:install) to install.
• Evaluate in the REPL (ql:add-to-init-file) to add Quicklisp to your Lisp init file.

Nyxt on GTK requires the latest version of the cl-webkit and cluffer libraries.

They are included as a submodule of this repository, so if you use the Makefile there is nothing to be done.

Otherwise clone each repository into ~/common-lisp (or another directory where ASDF will find it):

mkdir -p ~/common-lisp
git clone https://github.com/joachifm/cl-webkit ~/common-lisp/cl-webkit

• WebKitGTK+ also known as webkit2gtk (make sure to use the most recent version for security reasons)
• glib-networking (for WebKitGTK+)
• gsettings-desktop-schemas (for WebKitGTK+)
• libfixposix
• xclip (for clipboard support)
• enchant (for spellchecking)
• Debian-based distributions:

  sudo apt install sbcl libwebkit2gtk-4.0-dev glib-networking gsettings-desktop-schemas libfixposix-dev xclip enchant
      

• Fedora:

  sudo dnf install sbcl webkit2gtk3-devel glib-networking gsettings-desktop-schemas libfixposix-devel xclip enchant
      

• FreeBSD and derivatives

  pkg install sbcl webkit2-gtk3 glib-networking libfixposix xclip enchant
      

If your distribution does not install libraries in an FHS-expected location, you have to let know your Lisp compiler where to find them. To do so, add the library directories to cffi:*foreign-library-directories* list. For instance, if you are running Guix you may want to expose ~/.guix-profile/lib to the compiler by adding the following snippet to ~/.sbclrc:

(require "asdf")

(let ((guix-profile (format nil "~a/.guix-profile/lib/" (uiop:getenv "HOME"))))
  (when (and (probe-file guix-profile)
             (ignore-errors (asdf:load-system "cffi")))
    (push guix-profile
          (symbol-value (find-symbol (string '*foreign-library-directories*)
                                     (find-package 'cffi))))))

Install the WebKitGTK+ package of your distribution that provides libwebkit2gtk-4.0.so (the shared library for WebKitGTK+).

• For most Debian-based systems (including Ubuntu) this package is libwebkit2gtk-4.0-dev. Debian stable users are advised to make sure they use a recent-enough version, otherwise consider Debian Testing at least.
• For Arch Linux this package is webkit2gtk.

A note of caution about installing WebKit via your package manager: Your distribution supplied version of WebKit may not provide up-to-date versions of WebKit including the latest security patches. WebKitGTK+ tries to do the best job possible with maintaining security patches upstream, but it is also up to the the distribution provider to update their packages to take advantage of these fixes.

• GTK 3.24.12+
• WebKitGTK+
• XQuartz
• libfixposix

Nyxt on Qt requires the latest version of the cl-webengine library. Clone the cl-webengine repository into ~/common-lisp (or another directory where ASDF will find it):

mkdir -p ~/common-lisp
git clone https://github.com/atlas-engineer/cl-webengine.git ~/common-lisp/cl-webengine

Please follow the instructions in the cl-webengine repository for details about how to install it on your system.

• Qt 5 (qtbase, qtwebchannel, qtdeclarative)
• Qt 5 WebEngine
• libfixposix
• xclip (for clipboard support)
• enchant (for spellchecking)

• Qt 5.14.0+
• Qt WebEngine
• libfixposix

Clone the Nyxt repository into ~/common-lisp or any directory listed in asdf:*central-registry*:

mkdir -p ~/common-lisp
git clone https://github.com/atlas-engineer/nyxt ~/common-lisp/nyxt

The following command will build the Lisp core. On macOS this will produce an application bundle which you can copy into your /Applications folder.

• GNU/Linux:

  make all
      

• FreeBSD

  gmake all
      

• macOS:

  make all
  make app-bundle
      

Inside the Makefile you’ll find many options you can specify. You can specify to use your Lisp’s init file, to use your global installation of Quicklisp, or to automatically download and install a separate Quicklisp installation for Nyxt. Run make to display some documentation. Please see the Makefile for more details.

Start your Lisp and run the following commands:

(asdf:make :nyxt/gtk-application)

Your Lisp interpreter will have produced an executable in the directory where the asd file is located. You can also compile the Qt version like this:

(asdf:make :nyxt/qt-application)

If you use Quicklisp for Common Lisp library management outside the context of Nyxt, you may want to reuse your local distribution to build Nyxt.

To do so, invoke make with the following option:

make NYXT_INTERNAL_QUICKLISP=false ...

In this case, you’ll have to make sure the Quicklisp distribution is up-to-date or else future versions of Nyxt might fail to build. In a REPL:

(ql:update-dist "quicklisp")

If you use the internal Quicklisp distribution (i.e. with the default NYXT_INTERNAL_QUICKLISP=true), the distribution is updated automatically for you.

You will also need to manually update the Lisp specific dependencies.

For improved security while you browse the Internet, you can run Nyxt in a container on GNU/Linux.

• With Guix:

  guix environment --container --network --preserve='^DISPLAY$' --expose=/etc/ssl/certs --ad-hoc nss-certs nyxt -- nyxt
      

  If you want to load your configuration and use the data files:

  guix environment --container --network --preserve='^DISPLAY$' --expose=/etc/ssl/certs --expose="$HOME/.config/nyxt/" --share="$HOME/.local/share/nyxt"="$HOME/.local/share/nyxt/" --ad-hoc nss-certs nyxt -- nyxt
      

  If you get the following error:

  libGL error: failed to open /dev/dri/card0: No such file or directory
      

  add the --expose=/dev/dri/card0 option (change the path accordingly).

• With Firejail.

If you are developing Nyxt, you may prefer to run Nyxt directly from source so that you can skip the compilation step and iterate faster.

Make sure that Quicklisp is set up and up-to-date (see Update local Lisp libraries) as explained in the Quicklisp section.

Then in a shell execute the following:

1. $LISP to create a new Lisp REPL (replace $LISP with sbcl or any supported Common Lisp compiler).
2. Execute (require :asdf) if ASDF is not already loaded.
3. Execute (asdf:load-asd "/full/path/to/nyxt.asd") to load the Nyxt system definition (you must use absolute pathnames).
4. Execute (ql:quickload :nyxt/gi-gtk) to load the Nyxt system into your Lisp image.
5. Execute (nyxt:start) to open your first Nyxt window.

The above process is a bit cumbersome and you’ll probably want a more comfortable workflow from within your favourite editor. See the section about Emacs and SLIME, or see the Common Lisp Cookbook for a list of options for various editors.

SLIME provides a way of interacting with Nyxt, and with Lisp code in general (e.g. in a REPL).

From the SLIME manual:

SLIME extends Emacs with support for interactive programming in Common Lisp. The features are centered around slime-mode, an Emacs minor-mode that complements the standard lisp-mode. While lisp-mode supports editing Lisp source files, slime-mode adds support for interacting with a running Common Lisp process for compilation, debugging, documentation lookup, and so on.

To interact with a running instance of the Nyxt browser run the command start-swank. The minibuffer tells you the port where the server started (the default is 4006). Then, in Emacs run M-x slime-connect RET 127.0.0.1 RET 4006.

Notice that the default value of the variable *swank-port* in Nyxt is different from its counterpart variable slime-port in Emacs to avoid collisions with an *inferior-lisp* process. Both of these default values can be configured in the respective init files.

=SLY= is a fork of SLIME with additional functionality.

Follow the following steps:

1. Add the following line to your Nyxt init file

   (load-after-system :slynk "~/.config/nyxt/my-slynk.lisp")
       

2. Create a file called my-slynk.lisp where you will specify your start-slynk command

   (define-command-global start-slynk (&optional (slynk-port *swank-port*))
       "Start a Slynk server that can be connected to, for instance, in
   Emacs via SLY.
   
   Warning: This allows Nyxt to be controlled remotely, that is, to execute
   arbitrary code with the privileges of the user running Nyxt.  Make sure
   you understand the security risks associated with this before running
   this command."
       (slynk:create-server :port slynk-port :dont-close t)
       (echo "Slynk server started at port ~a" slynk-port))
       

3. Run the command start-slynk in Nyxt

Then proceed as in the previous SLIME section by relacing slime-connect with sly-connect.

There are several ways to ask for help from the community. The first and easiest one is to simply open up an issue with whatever problem you have. Feel free to open issues for any task, suggestion or conversation you wish to have.

There are a couple of resources out there to learn Common Lisp.

• Practical Common Lisp is a popular book available for free. It assumes you already know programming. It gives a good coverage of the “core” of the language and goes to the point.
• The Common Lisp Cookbook is a modern, community maintained resource covering many aspects of Common Lisp programming and beyond, from editor setup to style. The front page lists many other resources for learning, such as books (some available for free) and other web sites. If you already know another Lisp/Scheme, the cookbook can serve as a good crash course.

To contribute, please find a task on our issue tracker or within CHANGELOG.org document that has a TASK label affixed. Upon finding a task that you’d like to work on, ideally, ensure that it is not already being worked on.

After you have found a TASK item that is available:

• make a fork of the repository,
• add your changes,
• make a pull request.