Developing Extensions

Extension Features

Extensions are able to provide the following features to Gram:

• Languages
• Debuggers
• Themes
• Icon Themes

Developing an Extension

Before starting to develop an extension for Gram, be sure to install Rust via rustup.

Rust must be installed via rustup. If you have Rust installed via homebrew or otherwise, installing extensions will not work.

When developing an extension, you can use it in Gram by installing it:

From the extensions page, click the Install Local button (or the gram::InstallExtensionFromFolder action) and select the directory containing your extension.

If you need to troubleshoot, you can check the Gram.log (gram::OpenLog) for additional output. For debug output, close and relaunch the editor with the flag gram --foreground from the command line which show more verbose INFO level logging.

Directory Structure of a Gram Extension

A Gram extension is a Git repository that contains an extension.toml. This file must contain some basic information about the extension:

id = "my-extension"
name = "My extension"
version = "0.0.1"
schema_version = 1
authors = ["Your Name <you@example.com>"]
description = "My cool extension"
repository = "https://github.com/your-name/my-gram-extension"

In addition to this, there are several other optional files and directories that can be used to add functionality to a Gram extension. An example directory structure of an extension that provides all capabilities is as follows:

my-extension/
  extension.toml
  Cargo.toml
  src/
    lib.rs
  languages/
    my-language/
      config.toml
      highlights.scm
  themes/
    my-theme.json

WebAssembly

Procedural parts of extensions are written in Rust and compiled to WebAssembly. To develop an extension that includes custom code, include a Cargo.toml like this:

[package]
name = "my-extension"
version = "0.0.1"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
zed_extension_api = "0.1.0"

Use the latest version of the zed_extension_api available on crates.io. Make sure it's still compatible with Gram versions you want to support.

In the src/lib.rs file in your Rust crate you will need to define a struct for your extension and implement the Extension trait, as well as use the register_extension! macro to register your extension:

use zed_extension_api as zed;

struct MyExtension {
    // ... state
}

impl gram::Extension for MyExtension {
    // ...
}

gram::register_extension!(MyExtension);

stdout/stderr is forwarded directly to the Gram process. In order to see println!/dbg! output from your extension, you can start Gram in your terminal with a --foreground flag.

Extension License

Extension repositories should include a license. The following licenses are recommended:

• GNU GPLv3
• Apache 2.0
• BSD 3-Clause
• MIT

Your license file should be at the root of your extension repository. Any filename that has LICENCE or LICENSE as a prefix (case insensitive).

Note: This license applies only to your extension code itself. It does not apply to any tools your extension may download or interact with, such as language servers or other external dependencies. If your repository contains both extension code and other projects (like a language server), you don't need to relicense those other projects.