• Developer’s installation with Guix
• Developer’s installation with Nix
  • Building for local development
• Standard developer’s 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
• Run Nyxt in a security sandbox
• Hacking
  • Run from source
  • Interacting with a compiled version of Nyxt
    • SLIME
    • SLY/SLYNK
      • Quicklisp Setup
      • Non-Quicklisp Setup
  • Adding a new Lisp dependency
• Help & Community
  • Issue tracker
  • 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/nyxt.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 can load Nyxt with:

(asdf:load-system :nyxt/gtk-application)
(nyxt:start)

Nyxt is written in Common Lisp. It should build with any standard Common Lisp implementation but currently, only SBCL support is tested.

It is designed to be cross-platform, cross-engine compatible. Nyxt is available in both WebKit and WebEngine (experimental) flavors.

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: https://www.sbcl.org/platform-table.html. Full installation instructions can be found here: https://www.sbcl.org/getting.html.

If you wish to install it manually, system-wide, refer to the official Quicklisp website for instructions.

Then pass the NYXT_SUBMODULES=false option to all build commands, like this:

make NYXT_SUBMODULES=false ...

Each time you build Nyxt, you’ll have to make sure the Quicklisp distribution is up-to-date, otherwise the build might fail. In a Lisp REPL:

(ql:update-dist "quicklisp")

Nyxt requires some Lisp libraries and, since some are pinned at specific versions, relying on Quicklisp is discouraged.

All Lisp dependencies are included as a submodule of this repository, so unless the submodules are disabled (i.e. NYXT_SUBMODULES=false), there is nothing more to be done.

Otherwise clone the required repositories listed in .gitmodules into ~/common-lisp (or another directory where ASDF will find it). For instance, to get the latest version of cl-webkit, you would typically run the following:

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)
• gobject-introspection (for WebKitGTK+ bindings)
• glib-networking (for WebKitGTK+)
• gsettings-desktop-schemas (for WebKitGTK+)
• libfixposix
• xclip (for clipboard support)
• enchant (for spellchecking)
• pkg-config (for web-extensions)
• Debian-based distributions:

  sudo apt install sbcl libwebkit2gtk-4.0-dev gobject-introspection glib-networking gsettings-desktop-schemas libfixposix-dev pkg-config xclip enchant-2 libssl-dev
      

• Arch Linux:

  sudo pacman -S git sbcl cl-asdf webkit2gtk glib-networking gsettings-desktop-schemas enchant libfixposix
      

• Fedora:

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

• FreeBSD and derivatives

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

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))))))

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
• pkg-config

Notes:

1. If you install dependencies via MacPorts and your Lisp is SBCL, please try putting the following into your ~/.sbclrc:

   (ql:quickload :cffi)
   (pushnew "/opt/local/lib" cffi:*foreign-library-directories* :test #'equal)
       

2. To install the WebKitGTK+ dependency, you may want to install `webkit2-gtk(-devel)` instead of `webkit-gtk3` via your favorite package manager. If you are on a legacy version of macOS which is not supported by HomeBrew, you may want to try install these via MacPorts.

Qt is only required if you want to build Nyxt over the WebEngine renderer.

Warning: It’s highly experimental and may not build on master.

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)
• pkg-config (for web-extensions)

• Qt 5.14.0+
• Qt WebEngine
• libfixposix
• pkg-config

Clone the Nyxt repository into ~/common-lisp (or another directory where ASDF will find it):

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

Quicklisp contains stable releases of Nyxt. If you are reading this, you probably want to run cutting edge under development master branch of Nyxt (not the last stable release). Via Quicklisp, some users end up installing a stable release instead of running the frontier of Nyxt’s live GitHub repository. Thus, to access master branch do the git clone of Nyxt in ~/quicklisp/local-projects.

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 or to use your installation of Quicklisp 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)

or, alternatively for the QtWebEngine renderer:

(asdf:make :nyxt/qt-application)

Your Lisp implementation must have produced an executable in the directory where the .asd file is located.

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

• With Guix:

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

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

  guix shell --container --network --preserve='^DISPLAY$' --expose=/etc/ssl/certs --expose="$HOME/.config/nyxt/" --share="$HOME/.local/share/nyxt"="$HOME/.local/share/nyxt/" 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.

Steps:

1. Add the following lines to your Nyxt init file. If your Quicklisp directory differs, change it accordingly:

(load (merge-pathnames #p"quicklisp/setup.lisp" (user-homedir-pathname)))
(ql:quickload 'slynk)
;; Note: (nyxt-init-file) points to path/to/your/nyxt/config/directory
(load-after-system :slynk (nyxt-init-file "my-slynk.lisp"))

1. 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.
   
Waits for incoming connections, e.g. from 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))

1. Run the command start-slynk in Nyxt.
2. Proceed as in the previous SLIME section by replacing slime-connect with sly-connect.

If you aren’t using Quicklisp, you can configure Nyxt to start a Sly/Slynk server with the following steps.

Steps:

1. Ensure you have the Sly Package installed for Emacs with package-install. You may also clone the repository from here. Should you choose to clone the repository, see the appropriate section in step 2.
2. Add the following lines to your Nyxt’s init.lisp (the configuration file) depending on whether you are using the Emacs Sly package, or you cloned the repository:
   • If you have installed Sly with package-install (or similar method) in Emacs, add these lines to your nyxt/init.lisp :

(asdf:load-system :slynk)
(slynk:create-server :port 4008)

• If you are cloning from git, it’s the same as above but with an extra push expression:

(push #p"~/dir/to/newly/cloned/sly/dir" asdf:*central-registry*)
(asdf:load-system :slynk)
(slynk:create-server :port 4008)

1. Create a file called my-slynk.lisp in your Nyxt configuration directory (see (nyxt-init-file) where you will create a start-slynk command.

(define-command-global start-slynk (&optional (slynk-port *swank-port*))
  "Start a Slynk server.
   
Waits for incoming connections, e.g. from 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))

1. Run the command start-slynk in Nyxt with M-x start-slynk.
2. Proceed as in the previous SLIME section by replacing slime-connect with sly-connect. Remember to choose the correct port (in this case, 4008).

• Add and shallow clone upstream source as a Git submodule in ../_build/ directory.
• Add dependency name to ../nyxt.asd and documents/SOURCES.org.
• Add dependency to ../build-scripts/nyxt.scm, checking to make sure Guix already has it packaged.

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 or suggestion you wish to discuss.

See https://nyxt.atlas.engineer/learn-lisp for a few recommendations.

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.