lagrange

Lagrange

Lagrange is a cross-platform client for browsing Geminispace. It offers modern conveniences familiar from web browsers, such as smooth scrolling, inline image viewing, multiple tabs, visual themes, Unicode fonts, bookmarks, history, and page outlines.

Like Gemini, Lagrange has been designed with minimalism in mind. It depends on a small number of essential libraries. It is written in C and uses SDL for hardware-accelerated graphics. OpenSSL is used for secure communications.

Features

• Beautiful typography with full Unicode support
• Autogenerated page style and symbol for each Gemini domain
• Smart suggestions when typing the URL — search bookmarks, history, identities
• Sidebar for page outline, managing bookmarks and identities, and viewing history
• Multiple tabs
• Identity management — create and use TLS client certificates
• Audio playback: MP3, Ogg Vorbis, WAV
• Curses-based TUI as an alternative to the graphical interface
• And much more! Open about:help in the app, or see help.gmi

Downloads

Prebuilt binaries for Windows, macOS (10.13 or later) and Linux can be found in [Releases][rel]. You can also find Lagrange on Flathub for Linux.

On macOS you can install and upgrade via Homebrew:

brew install --cask lagrange

Please check MacPorts if you are using macOS 10.12 or older.

On Fedora and any RHEL/CentOS Stream 8 and 9 derivatives (RHEL, CentOS Stream, Alma, Rocky) that have the EPEL repos enabled:

sudo dnf install lagrange

On openSUSE Tumbleweed:

sudo zypper install lagrange

Using GNU Guix:

guix install lagrange

How to compile

You need a POSIX-compatible environment to compile Lagrange.

The required tools are a C11 compiler (e.g., Clang or GCC), CMake, pkg-config, and zip. Additional tools are required if HarfBuzz and GNU FriBidi are also compiled as part of the build (see next section for details).

1. Download and extract a source tarball from [Releases][rel]. Please note that the GitHub/Gitea-generated tarballs do not contain HarfBuzz, GNU FriBidi, or the_Foundation submodules; check which tarball you are downloading. Alternatively, you may also clone the repository and its submodules: git clone --recursive --branch release https://git.skyjake.fi/gemini/lagrange
2. Check that you have the build tools and dependencies installed: SDL (2.0.8 or newer), OpenSSL, libpcre, libunistring, GNU FriBidi, and zlib. For example,
   • on macOS using Homebrew: brew install cmake automake sdl2 [email protected] pcre libunistring fribidi
   • on Ubuntu: sudo apt install cmake zip libsdl2-dev libssl-dev libpcre3-dev zlib1g-dev libunistring-dev libfribidi-dev
   • on Fedora: sudo dnf install cmake zip SDL2-devel openssl-devel pcre-devel zlib-devel libunistring-devel fribidi-devel
3. Optionally, install the mpg123 decoder library for MPEG audio support. For example, the macOS Homebrew package is mpg123, on Ubuntu it is libmpg123-dev, and on Fedora it is mpg123-devel.
4. Create a build directory.
5. In your empty build directory, run CMake to configure: cmake {path_of_lagrange_sources} -DCMAKE_BUILD_TYPE=Release
6. Build it: cmake --build .
7. Now you can run lagrange, lagrange.exe, or Lagrange.app.

Unicode text rendering

Lagrange relies on the HarfBuzz and GNU FriBidi libraries for handling complex scripts and bidirectional text. This repository includes these two libraries as submodules. By default, if HarfBuzz and GNU FriBidi are not available on the system, they will be compiled as part of the app without any additional dependencies.

Note that compiling these libraries has the following requirements:

• HarfBuzz requires a C++ compiler.
• GNU FriBidi cannot be compiled with CMake; you need to have Meson and Ninja.

If these requirements cannot be met, or you would prefer the use the system-provided HarfBuzz and GNU FriBidi, please refer to the list of build options below: ENABLE_HARFBUZZ_MINIMAL and ENABLE_FRIBIDI_BUILD should both be set to NO. Note that a system-provided HarfBuzz likely has dependencies to other libraries, such as FreeType and GLib.

You also may disable HarfBuzz and/or GNU FriBidi entirely. The old text renderer that only supports non-complex left-to-right scripts is then used.

Installing to a custom directory

By default, the compiled app will be installed to a system-wide location determined by CMake.

Set CMAKE_INSTALL_PREFIX to install to a directory of your choosing:

1. cmake {path_of_lagrange_sources} -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/dest/path
2. cmake --build . --target install

Note that the install target also deploys an XDG .desktop file for launching the app.

Build options

CMake Option	Description
ENABLE_CUSTOM_FRAME	Draw a custom window frame. (Only on Microsoft Windows.) The custom frame is more in line with the visual style of the rest of the UI, but does not implement all of the native window behaviors (e.g., snapping, system menu).
ENABLE_DOWNLOAD_EDIT	Allow changing the Downloads directory via the Preferences dialog. This should be set to OFF in sandboxed environments where downloaded files must be saved into a specific place.
ENABLE_GUI	Build the GUI application (the default).
ENABLE_FRIBIDI	Use the GNU FriBidi library for processing bidirectional text. FriBidi implements the Unicode Bidirectional Algorithm to determine text directions.
ENABLE_FRIBIDI_BUILD	Compile the GNU FriBidi library as part of the build. If set to OFF, pkg-config is used instead to locate the library.
ENABLE_GAMEPAD	Allow gamepad UI input.
ENABLE_HARFBUZZ	Use the HarfBuzz library for shaping Unicode text. This is required for correctly rendering complex scripts and combining glyphs. If disabled, a simplified text shaping algorithm is used that only works for non-complex languages like English.
ENABLE_HARFBUZZ_MINIMAL	Build the HarfBuzz library with all dependencies disabled. Useful when building the app for distribution so that the number of deployed dependencies will be minimized. A system-provided version of HarfBuzz is likely built with dependencies on FreeType and ICU at least. If set to OFF, pkg-config will be used to find HarfBuzz.
ENABLE_IDLE_SLEEP	Sleep in the main thread instead of waiting for events. On some platforms, when using SDL 2.0.16 or earlier, SDL_WaitEvent() may have a relatively high CPU usage. Setting this to ON polls for events periodically but otherwise keeps the main thread sleeping, reducing CPU usage. The drawback is that there is a slightly increased latency reacting to new events after idle mode ends.
ENABLE_IPC	Instances of the Lagrange executable communicate via signals or (on Windows) a system-provided IPC mechanism. This is used for controlling an existing Lagrange window via the CLI. If set to OFF, each instance of the app runs without knowledge of other instances. This may cause them to overwrite each other's runtime files.
ENABLE_KERNING	Use kerning information in the fonts to adjust glyph placement. Setting this ON improves text appearance in subtle ways but slows down text rendering. It may be a good idea to set this to OFF when running on a slow CPU. This option only affects the simple built-in text renderer, and has no effect on HarfBuzz.
ENABLE_MAC_MENUS	Use native context menus on macOS.
ENABLE_MOBILE_HANDHELD	Use the mobile handheld UI variant. Assumes that a gamepad is used for controlling the app, ENABLE_GAMEPAD should also be set. It is suitable for handheld game consoles, for instance.
ENABLE_MOBILE_PHONE	Use the mobile phone UI variant. This replaces the sidebars with a sliding sheet and has other touch-friendly features. Settings and dialogs are presented as form-based sheets.
ENABLE_MOBILE_TABLET	Use the tablet UI variant. Sidebars are available as on the desktop, but Settings and dialogs are presented as form-based sheets.
ENABLE_MPG123	Use the mpg123 library for decoding MPEG audio files.
ENABLE_OPUS	Use the opusfile library for decoding Opus audio files.
ENABLE_POPUP_MENUS	Use popup windows for context menus. If OFF, menus are confined inside the main window.
ENABLE_RELATIVE_EMBED	Locate resources only in relation to the executable. Useful when any system/predefined directories are not supposed to be accessed, e.g., in the Windows portable build.
ENABLE_RESIZE_DRAW	Force the window to redraw while being resized. May be necessary on some platforms.
ENABLE_SPARKLE	Use the Sparkle framework for automatic updates. (macOS only)
ENABLE_STATIC	Link dependencies statically.
ENABLE_TUI	Build the TUI application (clagrange). The SEALCurses library is required (it replaces SDL); check that the lib/sealcurses submodule is checked out.
ENABLE_WEBP	Use libwebp to decode .webp images, if pkg-config can find the library.
ENABLE_JXL	Use libjxl to decode .jxl images, if pkg-config can find the library.
ENABLE_WINDOWPOS_FIX	Set correct window position after the window has already been shown. This may be necessary on some platforms to prevent the window from being restored to the wrong position.
ENABLE_WINSPARKLE	Use WinSparkle for automatic updates. (Windows only)
ENABLE_X11_SWRENDER	Default to software rendering when running under X11. By default Lagrange attempts to use the GPU for rendering the user interface. You can also use the --sw option at launch to force software rendering.
ENABLE_X11_XLIB	Use the Xlib API directly under X11. This is used for window decoration color theming, for example.

Compiling the TUI version

Lagrange has a text-mode interface that enables running the app in a terminal. However, it is mutually exclusive with the graphical interface, which means that the GUI and TUI are built as separate executables. By default, the TUI is disabled in the build settings. Set the ENABLE_TUI option to YES to build the TUI executable. If the GUI is not needed, you can also set ENABLE_GUI to NO. The TUI executable is called clagrange.

In the TUI build, SDL is replaced with a library called SEALCurses that implements a subset of the SDL API on top of Curses. The requirements for building the TUI are otherwise the same as with the GUI, except HarfBuzz, FriBidi, and all the image and audio dependencies will not be used.

Compiling on macOS

When using OpenSSL from Homebrew, you must add its pkgconfig path to your PKG_CONFIG_PATH environment variable, for example:

export PKG_CONFIG_PATH=/opt/homebrew/Cellar/[email protected]/1.1.1i/lib/pkgconfig

Also, SDL's trackpad scrolling behavior on macOS is not optimal for regular GUI apps because it emulates a physical mouse wheel. This may change in a future release of SDL, but at least in 2.0.14 (and earlier) a small patch is required to allow momentum scrolling to come through as single-pixel mouse wheel events. Note that SDL comes with an Xcode project; use the "Shared Library" target and check that you are doing a Release build.

Compiling on Windows

Windows builds require MSYS2. In theory, Clang or GCC (on MinGW) could be set up na