Contents

• Developer Installation
  • OSX Instructions
  • Linux Instructions
  • Running nEXT
  • Compiling nEXT (under active development)
• Release Timeline
  • 0.05
  • 0.04
  • 0.03
  • 0.02
  • 0.01
• Contributing

Developer Installation

nEXT browser is built with ECL and EQL, and is designed to be cross platform compatible. To download a prebuilt-binary, please see the “Releases” section of this repository.

OSX Instructions

Installing Xcode Command Line Tools

Before installing anything, install the Xcode Comand line tools. To install the Xcode Command Line tools on OSX execute the following in a terminal:

xcode-select --install

To verify that the command tools were successfully installed type:

xcode-select -p

the output of this command should be the path at which the command line tools are installed.

Installing QT5 (Cross Platform GUI Toolkit)

QT5 is available from a number of sources, the easiest is to install it via a package manager such as Macports or Brew. However you install, ensure that you install it with webkit support.

You can install QT5 via Macports with the following command:

port install qt5

You can also install QT5 via the official qt installer:

https://www.qt.io/download/

To test your installation/version of QT, execute qmake --version.

Installing ECL (Embeddable Common Lisp)

Compilable tarballs can be found on the ECL website:

https://common-lisp.net/project/ecl/static/files/release/

To verify your installation of ECL:

• Execute /usr/local/bin/ecl, it should show an ECL Prompt
• Verify the contents of /usr/local/lib contain the ecl libraries.
• Verify the contents of /usr/local/include/ecl contain the header files

Installing Quicklisp

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 ecl --load quicklisp.lisp to load quicklisp
• Evaluate in the REPL (quicklisp-quickstart:install) to install
• Evalute in the REPL (ql:add-to-init-file) to add quicklisp to your ecl init file

more detailed instructions and other resources are readily available on the quicklisp website.

Installing EQL5 Library & Executable (Embedded QT Lisp)

The source for EQL5 is available here:

https://gitlab.com/eql/EQL5

To build and install the EQL Library/Executable:

1. Clone the Repository into a directory where you plan to keep the installation, this cannot be moved after installation.
2. In src/ exec: ecl -shell make.lisp This command generates src/libini_eql5.a.
3. Edit src/eql5.pro commenting out all QT modules you do not require.
   • The webkit module is required for nEXT.
4. In src/ exec: qmake eql5.pro. This command generates the makefile.
5. In src/ exec: make
6. In src/ exec: sudo make install

To test your installation exec eql5 -qgui, you should presented with a REPL and a GUI.

After the installation, the following should be completed:

• /usr/local/bin contains an eql5 executable
• /usr/local/include contains a folder named eql5
• /usr/local/lib contains all built QT modules (selected in src/eql5.pro) and libeql \*.dylib files

Linux Instructions

Due to the large variances in Linux distributions: file locations, package managers, and best practices, this installation guide attempts to make as few decisions as possible- instead opting to list the requirements necessary to build nEXT.

Installing a compiler

Install a C/C++ Compiler

Installing QT5

Install QT directly from QT: download QT, or install via third party package manager sources, apt-get etc.

Installing ECL (Embeddable Common Lisp)

Compilable tarballs can be found on the ECL website: download ECL

Installing Quicklisp

The official quicklisp website can provide updated links to downloads, and instructions:

To install quicklisp:

• Download https://beta.quicklisp.org/quicklisp.lisp
• Execute ecl --load quicklisp.lisp to load quicklisp
• Evaluate in the REPL (quicklisp-quickstart:install) to install
• Evalute in the REPL (ql:add-to-init-file) to add quicklisp to your ecl init file

more detailed instructions and other resources are readily available on the quicklisp website.

Installing EQL5 Library & Executable (Embedded QT Lisp)

The source for EQL5 is available here:

https://gitlab.com/eql/EQL5

To build and install the EQL Library/Executable:

1. Clone the Repository into a directory where you plan to keep the installation, this cannot be moved after installation.
2. In src/ exec: ecl -shell make.lisp This command generates src/libini_eql5.a.
3. Edit src/eql5.pro commenting out all QT modules you do not require.
   • The webkit module is required for nEXT.
4. In src/ exec: qmake eql5.pro. This command generates the makefile.
5. In src/ exec: make
6. In src/ exec: sudo make install

To test your installation exec eql5 -qgui, you should presented with a REPL and a GUI.

After the installation, the following should be completed:

• /usr/local/bin contains an eql5 executable
• /usr/local/include contains a folder named eql5
• /usr/local/lib contains all built QT modules (selected in src/eql5.pro) and libeql \*.dylib files

Running nEXT

From the directory next/ execute the following command to run:

1. eql5 run

You should be presented with a QT Window. To test that everything is working execute the following commands:

1. C-l
2. A minibuffer should pop-up in which you can enter text

From the terminal that you launched nEXT you’ll be able to see output from the program. You can additionally create a REPL during runtime in the following way: eql5 run -qgui.

If an exception or crash occurs, you’ll be presented with a REPL that you can use to debug the program.

Compiling nEXT (under active development)

OSX Instructions

From the directory next/ execute the following commands to compile:

1. eql5 make

Now you should have a compiled next.app, simply execute this app to start nEXT browser.

Release Timeline

Major releases are issued by incrementing the first digit. That is, release 1.20, and 2.20 are one major release away from each other. Minor releases are issued by incrementing by 0.01. That is, 1.01, and 1.02 are two minor releases following major release 1.0.

0.05

Window System

• Emacs like window system

Add REPL

• Add slime support

Create Page class with meta information about page

• Use this as data field in tree
• Use a method from this class for persistence

History

• History will be stored in a db (possibly sqlite) with additional metadata that allows searching semantically, as well as searching by different criteria.

History is searchable

• History has a query language that can be used to look for different things (e.g. date, include exclude regex, etc)

0.04

Isolate backend QT Code

• Break apart QT code into separate file
• Remove all top-level side effects
• Modularize GUI backend

Write Cocoa backend

• Use CCL Cocoa Library to use native webkit backend

Bookmarks

• Bookmarks will be stored in a db (possibly sqlite) with information about them, they’ll be navigable via a completion buffer

0.03

Write Manual Base

• Write basic information and configuration within the manual as a “users” guide

Improve in Code Documentation & Architecture

• Create much clearer picture of how everything functions together, make cleaner architecture diagrams showing how everything links together
• Document all functions

OSX Compilation

• Modify make.lisp script to create a binary that grabs all of the dependencies and creates a executable that can be deployed on OSX
• Use `macdeployqt` to copy the core qt libraries to `next.app/Contents/Frameworks`
• Use `otool -L next.app/Contents/MacOS/next` to find the linked frameworks that are not located in `next.app/Contents/Frameworks`, manually copy them to `next.app/Contents/Frameworks`
• Use install_name_tool to update the now copied frameworks in `next.app/Contents/Frameworks`
• For more info please see: http://doc.qt.io/qt-5/osx-deployment.html

Kill Buffer

• Add function to kill buffer, bind to C-k

0.02

History Tree Mode

• Create a mode that allows traversal of the tree created in the history of a document-mode buffer

Cancel Within Minibuffer mode

Within document-mode the history will be represented as a tree

• forwards and backwards navigation creating new nodes and

traversals. This will allow for all points in history to be reachable, and a future expansion designed to recreate the functionality offered by undo-tree: https://www.emacswiki.org/emacs/UndoTree

Ability to navigate forward and backward in history

• using the key binding M-f, and M-b for forward and backward respectively
• should only work if there is one child

Forward navigation with more than one child prompts mini-buffer selection

• If a user tries to navigate forward but there is more than one possible destination available, show the possibilities as an auto-completable list in the minibuffer

CLOS

• Convert struct usage to CLOS

Scrolling

• The ability to scroll up and down within a document
  • using C-n to scroll down
  • using C-p to scroll up

0.01

This version describes the minimum usability as a basic browser, with the following features:

• Implementation of document-mode, the major-mode that all modes extend
• Ability to set key bindings for major modes
• Ability to browse and change buffers using C-x b

Definitions

Buffer: All documents are contained in an object type called a buffer. As an example, a document on the web located at http://www.url.com can be contained in a buffer with a similar name. A buffer is composed of all elements (text, bitmaps, etc) necessary to render a single document.

Mode-map: A keyboard hot-key to function mapping.

Minibuffer: A special buffer dedicated to interacting with nEXT commands in progress. This buffer appears at the bottom of the screen and is collapsed when not in use.

Major-mode: A major mode is defined as the primary mode of interacting with a particular buffer. A mode defines a set of key bindings, hooks for actions, and presentation details for a given view. At any given time, there may only be one major mode for a buffer. All major modes are composed of entirely lower case alpha with dashes used as a separator. Every major mode has a keyboard mapping that follows this pattern: document-mode, will have a mode map called document-mode-map.

Minor-mode: A minor mode is a secondary mode of modifying a buffer’s behavior and content. There can be an infinite amount of minor modes applied to a given buffer. All minor modes are composed of entirely lower case alpha with dashes used as a separator.

Major mode: document-mode

All major modes inherit from document mode. Document mode provides the basic framework for mapping global commands and defining general behavior.

Document-mode will be the basic major mode for opening documents on the web. document-mode will extend document-mode, and thus will inherit all of its key bindings. If there is a conflict of key bindings, the lowest scope key binding will be prioritized. As a concrete example, all bindings defined in a minor mode will override any defined in document-mode. In the first release, document-mode will support the following key bindings and features:

For the first release, document-mode must have:

Ability to open a new html document with the key binding C-l

Opening of new pages in the same buffer can be invoked by the key binding C-l. This key binding will open up the Minibuffer and prompt the user to enter the url which they would like to visit.

Ability to open new buffers with the key-binding M-l

Opening of new buffers by invoking M-l will open the Minibuffer. Within the Minibuffer, the user will be presented with a prompt in which they can enter in the url they would like to visit in a new buffer.

• May possibly switch implementation to “hide” rather than “close” widgets, possibly using a widget pool as well for memory performance

Ability to set Key bindings

The following syntax should be used to set a key binding:

(define-key x-mode-map (kbd “C-h”) ‘function)

Where x-mode-map is a keymap relating to a mode (major or minor).

Where ‘function is a function that is passed to define-key to trigger a function upon a key press.

(kbd “C-h”) defines that the keyboard sequence Control + h is represented. For the keyboard syntax, the following keys are described:

• S = super key (windows/command key)
• C = control key
• M = meta key (alt key)

A chain of key bindings may be set in the following manner:

(kbd “C-x C-s”) will denote the following key presses, Ctrl + x, followed by Ctrl + s immediately thereafter.

Upon the definition of a “chained” keyboard binding, any elements in the chain may not be used individually. For example, binding “C-x C-s”, will prohibit the binding of “C-x” by itself. This is because there would be ambiguity in regards to which key binding is intended to be invoked.

Ability to browse and change buffers

The user will be able to invoke the key binding C-x b to bring up a menu in the Minibuffer in which they will be able to select a new buffer to bring to focus.

Minibuffer Completion

Switch buffer should demonstrate an example of minibuffer completion candidates

Compilation OSX

• One “click” build system for deployment on OSX
• Organization of build systems into lisp files, no shell scripts

Contributing

Please find a task within this document that has a TODO label affixed. Upon finding a task that you’d like to work on, email the mailing list next-browser@googlegroups.com with the TODO item and a simple example of a proposed solution.

After you have found a TODO item that is available:

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