Skip to content

Latest commit

 

History

History
511 lines (382 loc) · 17.8 KB

README.org

File metadata and controls

511 lines (382 loc) · 17.8 KB
Raw

Nyxt Developer’s Manual

Table of contents

Developer’s installation with Guix

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.

Developer’s installation with Nix

Building for local development

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)

Standard developer’s installation

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.

Installing SBCL

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.

Installing Quicklisp (optional)

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

GTK dependencies

Lisp dependencies

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

GNU/Linux, FreeBSD GTK dependencies

  • 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.

macOS specific dependencies

  • 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 dependencies

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.

Lisp dependencies

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.

GNU/Linux, FreeBSD dependencies

  • Qt 5 (qtbase, qtwebchannel, qtdeclarative)
  • Qt 5 WebEngine
  • libfixposix
  • xclip (for clipboard support)
  • enchant (for spellchecking)
  • pkg-config (for web-extensions)

macOS dependencies

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

Fetch the source code

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

Observation

Quicklisp publishes stable releases of Nyxt, but you probably want to run cutting edge master branch of Nyxt (not the latest stable release). Via Quicklisp, some users end up installing a stable release instead of running the frontier of Nyxt’s GitHub repository. To have the frotier, please clone Nyxt’s repository at ~/quicklisp/local-projects.

Compile

Using the Makefile

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.

Using Lisp

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.

Run Nyxt in a security sandbox

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.

Hacking

Run from source

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.

Interacting with a compiled version of Nyxt

SLIME

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/SLYNK

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

Quicklisp Setup

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.

Non-Quicklisp Setup

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

Adding a new Lisp dependency

Help & Community

There are several ways to ask for help from the community.

Issue tracker

The first and easiest one is to simply open up an issue with whatever problem or suggestion you wish to discuss.

Learning Common Lisp

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

Contributing

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.

IRC Channel

You can find Nyxt on Libera IRC: #nyxt