Skip to content

Update the “Building Pulsar” docs… #41

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
savetheclocktower merged 4 commits into from
Mar 12, 2026
Merged

Update the “Building Pulsar” docs… #41

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4205aa9
Update the “Building Pulsar” docs to agree with the status quo
savetheclocktower Jan 4, 2026
69c95b2
Address PR feedback
savetheclocktower Mar 11, 2026
cab85cc
Address more feedback
savetheclocktower Mar 12, 2026
5c5c0b4
Address final feedback
savetheclocktower Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 97 additions & 37 deletions docs/contributing-to-pulsar/building-pulsar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,6 @@ title: Building Pulsar
layout: doc.ejs

---
<!-- TODO check all of this for accuracy, and if we want to keep these install instructions -->

<!-- TODO: It’s absolutely possible to hack on Pulsar’s core without building it… by setting `ATOM_DEV_RESOURCE_PATH`. I’ve never had to build Pulsar from source. I don’t know if there are any caveats, but we should find a way to mention that as an option. — @savetheclocktower -->

If you want to investigate a bug, implement a new feature in Pulsar’s core, or just tinker, you’ll need to build and run Pulsar from source.

Expand All @@ -16,47 +13,58 @@ The Pulsar application code can be found in the

To build Pulsar you will need to meet some basic requirements:

- Node.js (version specified in [pulsar/.nvmrc](https://github.com/pulsar-edit/pulsar/blob/master/.nvmrc),
recommended installation is via [nvm](https://github.com/nvm-sh/nvm))
- yarn (enable with `corepack enable`)
- Git
- Python
- C++ toolchain
- [Libsecret](https://wiki.gnome.org/Projects/Libsecret) development headers
- An installation of Node. We endeavor to keep `.nvmrc` updated with the best version of Node to use (allowing users of [nvm](https://github.com/nvm-sh/nvm) to select the correct version more easily), but technically the best version of Node to use is [the one that corresponds to the version of Electron that’s being used on the `master` branch](https://releases.electronjs.org/release) (or whichever branch you’re building).

You can determine the correct version of Electron by looking for the `electronVersion` key in [`package.json`](https://github.com/pulsar-edit/pulsar/blob/master/package.json) for the branch you’re building.

We strongly recommend that you use a version manager like [nvm](https://github.com/nvm-sh/nvm) or [asdf](https://asdf-vm.com/) instead of relying on whatever Node may be installed globally on your system.

For OS or distribution specific instructions see below:
- yarn (enable with `corepack enable`; further instructions below).
- Recent versions of Git and Python 3.
- A C++ compilation toolchain.

For OS- or distribution-specific instructions, see below:

::: tabs#core-hacking

@tab Linux

On Linux, certain libraries must be installed in order to build Pulsar:

- Standard packages for compiling code (`gcc`, `make`, etc.) — often available bundled into their own package
- [`libsecret`](https://wiki.gnome.org/Projects/Libsecret) development headers (for storage of secrets)
- `libx11` and various libraries relating to [XKB](https://www.x.org/wiki/XKB/) (so that Pulsar can detect and handle keyboard layouts in X11)
- `libwayland` (so that Pulsar can detect and handle keyboard layouts in [Wayland](https://en.wikipedia.org/wiki/Wayland_(protocol)))

Listed below are the specific packages believed to be necessary for various distributions. If any of these are wrong or insufficient, please [open an issue](https://github.com/pulsar-edit/documentation/issues) so we can keep these instructions accurate.

### Ubuntu/Debian

```sh
# Install development packages
apt install build-essential libxkbfile-dev libsecret-1-dev libx11-dev
apt install build-essential libsecret-1-dev libx11-dev libxkbfile-dev libxkbcommon-dev libxkbcommon-x11-dev libxkbcommon0 xkb-data libwayland-dev libwayland-client0 python3-setuptools pkg-config
```

### Fedora/RHEL

```sh
# Install development packages
dnf --assumeyes install make gcc gcc-c++ glibc-devel git-core libsecret-devel rpmdevtools libX11-devel libxkbfile-devel nss atk gdk-pixbuf2 gtk3 mesa-dri-drivers
dnf --assumeyes install make gcc gcc-c++ glibc-devel git-core libsecret-devel rpmdevtools libX11-devel libxkbfile-devel libxkbcommon-devel nss atk gdk-pixbuf2 gtk3 mesa-dri-drivers wayland-devel libwayland-client
```

### Arch

```sh
# Install the development packges
pacman -S base-devel libxkbfile libsecret libx11 libxcrypt-compat
# Install development packges
pacman -S base-devel libxkbfile libsecret libx11 libxcrypt-compat libxkbcommon libxkbcommon-x11 wayland
```

### OpenSUSE

```sh
# Install development packages
zypper in -t pattern devel_basis
zypper in libX11-devel libxkbfile-devel libsecret-devel
zypper in libX11-devel libxkbfile-devel libsecret-devel libxkbcommon libxkbcommon-x11-0 libxkbcommon0 libwayland-client0 wayland
```

@tab macOS
Expand All @@ -69,84 +77,136 @@ You can run `xcode-select --install` to setup these build tools if you think the

Install all of the components described on the [Installing dependencies for some community packages](/getting-started/dependencies-for-some-community-packages/#installing-visual-studio-tools) page.

In particular, you must have either Visual Studio or Visual Studio Tools (_not_ Visual Studio Code) and the “Desktop development with C++” component must be enabled.
In particular, you must have either [**Visual Studio** or **Build Tools for Visual Studio**](https://visualstudio.microsoft.com/downloads/) (Visual Studio Code isn’t the same thing!) and the “Desktop development with C++” and “Windows 10 SDK” components _must_ be enabled.

If you don’t have either one installed and you want to get set up quickly, install Visual Studio Tools as directed in the instructions above.

:::

## Building and running the application

To build the application so you can start hacking on the core you will need to download the source code to your local machine and `cd` to the pulsar directory:
### Check out the code

First, check out the source to a directory of your choosing.

```sh
git clone https://github.com/pulsar-edit/pulsar.git && cd pulsar
```

Install Node (we recommend using `nvm`; see above) and enable corepack (for `yarn`). This will install the version of Node specified in [pulsar/.nvmrc](https://github.com/pulsar-edit/pulsar/blob/master/.nvmrc):
### Pick the right Node version and ensure Yarn is present

Switch to the correct version of Node for the project; if you’re running `nvm`, this should be as simple as `nvm install` (which will install the version of Node specified in specified in [pulsar/.nvmrc](https://github.com/pulsar-edit/pulsar/blob/master/.nvmrc), or else use it if it’s already installed). Then, in order to get `yarn`, you’ll need to run `corepack enable`.

```sh
nvm install
nvm install # Or the equivalent for your version manager
corepack enable
```

If Node is already installed, run the following to make sure the correct version of Node is being used (see [requirements](#requirements-and-dependencies)):
You’ll only need to run `corepack enable` the first time for a given version of Node.

```sh
nvm use
node -v
```
Certain tool version managers might require a “reshim” step here; for instance, if you’re using `asdf`, you should run `asdf reshim` to ensure it creates a shim executable for `yarn`.

### Initialize the submodules

Run the following to initialize and update the submodules:

```sh
git submodule init && git submodule update
```

Now install and build Pulsar & `ppm`:
### Build the dependencies

For reasons mainly having to do with dependency resolution, we use `yarn` rather than `npm` for installing dependencies.

Here’s how to install the dependencies for Pulsar and `ppm`:

```sh
yarn install
yarn build
yarn build:apm
```

Start Pulsar!
Depending on which option you choose below, `ppm` might need [additional configuration](https://docs.pulsar-edit.dev/contributing-to-pulsar/using-ppm/).

### Option 1: `yarn start`

Here your options diverge; you can choose the one that fits your style of development best.

The first option is to run the `start` task; it’ll spawn a debug copy of Pulsar by invoking the `electron` binary directly. Logging information will go into your terminal.

```sh
yarn start
```

These instructions will also build `ppm` (Pulsar Package Manager) but it will require some [additional configuration](/contributing-to-pulsar/using-ppm/) for use.
### Option 2: `ATOM_DEV_RESOURCE_PATH`

If you have Pulsar installed already, you don’t have to build your own copy just to run it from source. Instead, do this:

1. Ensure no instance of Pulsar is currently running.
2. Set the `ATOM_DEV_RESOURCE_PATH` environment variable to the full path of where the Pulsar source code exists on disk.
3. Launch Pulsar with the `--dev` flag so that dev mode is enabled.

The exact method of doing so varies by platform, but on macOS/Linux you could do:

```sh
ATOM_DEV_RESOURCE_PATH=/path/to/pulsar pulsar --dev .
```

[direnv](https://direnv.net/) is a handy way of associating certain environment variables with certain working directories and might make this workflow even easier.

### Option 3: Build binaries

The first two options are great for iterating on changes to the Pulsar source code, but they don’t actually _build_ the app as a standalone binary. For that you need the build script, invoked via `yarn dist`.

## Building binaries
The build script will detect your OS and build the right binary for it; it’ll also automatically build for your system’s CPU architecture. For example, building on an `x86_64` CPU will produce binaries for `x86_64`, and building on `arm64` will only produce binaries for `arm64`. After running you will find your built application in `pulsar/binaries`.

The following will allow you to build Pulsar as a stand alone binary or installer. After running you will find your built application in `pulsar/binaries`.
:::note Caveats

The build script will automatically build for your system’s CPU architecture. For example, building on an `x86_64` CPU will produce binaries for `x86_64`, and building on `arm64` will only produce binaries for `arm64`.
It is not possible to “cross-build” for different OSes; for instance, if you want a Linux binary, you must generate it from a Linux machine.

It is also not _currently_ possible to build for one processor architecture from another, but we hope to make this easier soon.

:::

It is not possible to “cross-build” for different OSes. For Linux binaries you must build from a Linux machine; macOS binaries must be built from macOS; and so on. Your OS is detected automatically and the script will build the correct binaries for it.

::: tabs#core-hacking

@tab Linux

By default, running `yarn dist` will attempt to create `AppImage` (for most Linux distributions), `deb` (for Debian or Ubuntu based distributions) and `rpm` (for Red Hat or Fedora based distributions) binaries but you can select the actual target you want to build by appending the above targets to the command. e.g.:
Running `yarn dist` will attempt to create all four variants: `tar.gz` (suitable for most Linux distributions), `AppImage` (suitable for most Linux distributions and more self-contained than the `tar.gz`), `deb` (for Debian or Ubuntu based distributions), and `rpm` (for Red Hat or Fedora based distributions) binaries.

<!-- TODO: This is not currently true, but it is a good idea! Uncomment when we add this in.

@Daeraxa Daeraxa Mar 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this change? I'm sure this used to work as I was building a lot of RPMs and Appimages trying to solve an issue and it definitely only produced the specified targets at the time.

@savetheclocktower savetheclocktower Mar 12, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't remember if I checked it or not, but there did not seem to be any accounting for such arguments in our electron-builder.js script. I opened a PR to add it back in explicitly.

@savetheclocktower savetheclocktower Mar 12, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On macOS, at least, yarn dist dmg and yarn dist zip do not work; the script tries to build both targets no matter what.

@Daeraxa Daeraxa Mar 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair enough, I just remember using this because it massively cut down on the time to produce binaries to test (it was stuff to do with the appimage apprun and the rpm install issues)

@savetheclocktower savetheclocktower Mar 12, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I guess it must've been removed at some point.

@DeeDeeG DeeDeeG Mar 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sems the CLI arguments for this are a little different than our docs presumed:

[ . . . snipped . . . ]

Building:
  --mac, -m, -o, --macos   Build for macOS, accepts target list (see
                           https://www.electron.build/mac)               [array]
  --linux, -l              Build for Linux, accepts target list (see
                           https://www.electron.build/linux)             [array]
  --win, -w, --windows     Build for Windows, accepts target list (see
                           https://www.electron.build/win)               [array]
  --x64                    Build for x64                               [boolean]
  --ia32                   Build for ia32                              [boolean]
  --armv7l                 Build for armv7l                            [boolean]
  --arm64                  Build for arm64                             [boolean]
  --universal              Build for universal (mac only)              [boolean]
  --dir                    Build unpacked dir. Useful to test.         [boolean]
  
  [ . . . snipped . . . ]

From: https://www.electron.build/cli


But you’ll probably want to build just one of these four. So you can select the actual target you want to build by appending the targets you want to build to the command:

- `yarn dist appimage`
- `yarn dist deb`
- `yarn dist rpm`
- `yarn dist targz`

You can also specify more than one — for instance, `yarn dist appimage targz` — to build those targets and skip the others.

-->

@tab macOS

`yarn dist` will create a `dmg` installer. There are currently no additional targets for macOS.
`yarn dist` will create a `.dmg` and a `.zip`. These are nearly identical in practice.

As noted above this builds for your current CPU architecture. On an Intel Mac this will create Intel binaries; on Apple silicon (M1, M2, etc.) this will create Apple silicon binaries.
As noted above, the build will be targeted to the system’s CPU architecture. On an Intel Mac this will create Intel binaries; on Apple silicon (M1, M2, etc.) this will create Apple Silicon binaries.

@tab Windows

By default, running `yarn dist` will attempt to create an `NSIS` installer as well as a `Portable` executable which does not require installation. If you only wish to build one then you can specify it by appending the above targets to the command e.g.:
<!-- TODO: Is the below still true? Check it to be sure. -->

By default, running `yarn dist` will attempt to create an `NSIS` installer as well as a “portable” executable which does not require installation.

<!-- TODO: Not true, but should be soon. Uncomment when it’s true!

If you wish to build only one, you can specify it by appending the appropriate target to the command:

- `yarn dist nsis`
- `yarn dist portable`
- `yarn dist zip`

-->

:::