Comprehensive build documentation missing

[ottok]

Hi!

I am currently looking into packaging Pulsar Edit for Debian. Due to that I wanted to read all the docs on what build dependencies Pulsar has (and ideally why), and also how to build it. I noticed that the current documentation is quite lacking.

The CONTRIBUTING.md doc section Local development simply refers to https://flight-manual.atom.io which does not exist anymore.

It has been replaved by https://docs.pulsar-edit.dev/, which in section Building Pulsar which does explain some things, but for e.g. dependencies it is very short and does not even mention what NodeJS version is needed or why Libsecret is needed (in my testing it isn't) and it does not really explain the custom script/electron-builder.js which in fact orchestrates everything.

The sources also have the docs/ subdirectory, and docs/Building.md, but they seem unmaintained and duplicate with the online documentation site docs.pulsar-edit.dev..

The most up-to-date build instructions can be found by looking at the CI code itself in .github/workflows/build.yml and .github/workflows/package-tests-linux.yml. However, there isn't much inline documentation explaining why the build is done as it is done, and some oddities like using npx yarn instead of just yarn baffles me.

There are also a .cirrus.yml file with build commands, and a Dockerfile with dependency lists, but seems to be nothing is using these. The Dockerfile is based on Ubuntu 20.04 but the GitHub Actions is running on Ubuntu 25.10, so probably nobody has used the Dockerfile for a long time.

There is also the git submodule ppm with it's own quirks which is part of the overall Pulsar build.

I started now documenting the build (for Ubuntu 24.04 specifically, as the CI probably and releases should probably be based on it) at ottok@606fb2e#diff-08eb1fbe8a9312a406bcf21cf33836ee9106c0de525e5d77de5321747102e05f. I filed this issue to solicit feedback about the state of the build documentation and perhaps some guidance what should be done about it. If I figure out how all of this works I might submit a PR to have the docs and build scripts consolidated, streamlined and up-to-date.

[savetheclocktower]

It has been replaved by https://docs.pulsar-edit.dev/, which in section Building Pulsar which does explain some things, but for e.g. dependencies it is very short and does not even mention what NodeJS version is needed or why Libsecret is needed (in my testing it isn't)

In theory, it doesn't mention the needed Node version because the .nvmrc file will contain that information, but I doubt it's up to date, so it's good you've called this out. I don't use nvm personally so I'd certainly forget to keep this metadata up to date if it were up to me.

Technically speaking, the correct version of Node to use is the exact version of Node that is bundled with our current version of Electron. For example: right now master is on Electron 30.0.9, and that corresponds to Node 20.11.1. ppm’s version of Node must synchronize with this, hence the contents of BUNDLED_NODE_VERSION.

It is true that yarn dist does the bulk of the work via script/electron-builder.js; I'm not sure which parts of that could use further explanation, so please elaborate on what could be better documented. That build process should produce platform-appropriate artifacts — e.g., a .deb file on Linux.

I suspect libsecret is needed for ppm rather than Pulsar itself — keytar probably uses it to store your GitHub token if you publish packages.

I am a bit curious about why you're going to all this trouble when a .deb file is one of our installation mechanisms — is something about it not working for you on Debian?

[savetheclocktower]

There are also a .cirrus.yml file with build commands, and a Dockerfile with dependency lists, but seems to be nothing is using these. The Dockerfile is based on Ubuntu 20.04 but the GitHub Actions is running on Ubuntu 25.10, so probably nobody has used the Dockerfile for a long time.

As for this: @DeeDeeG set this up, and I believe the idea is that the GitHub Action uses Docker within itself so that it can use an intentionally old version of Ubuntu. The motivation was to build the app using the oldest version of some dependencies that we could get away with, as they tend to be more forward-compatible than they are backward-compatible. I don't know exactly which dependencies this applies to, but presumably this makes it so that we're not inadvertently shutting out users of older OS versions.

[ottok]

Node version: I discovered the build automatically downloads NodeJS 20 anyway, so it does not matter that package.json and .nvmrc refer to NodeJS 14 and 16. I am currently testing updating them both to 20 in https://github.com/ottok/pulsar/tree/dev-otto but version 14 is all over the CI pipeline code and it wasn't easy to figure out what is actually used and what not.

It is quite clear to me now what the build depends on, and I filed #1395 to help any other potential contributor get up and running quickly. It is however unclear to me what all is necessary and what is unnecessary considering the amount of legacy stuff in the build scripts. Cleaning away some clearly obsolete stuff would help keep the code base leaner and easier for new contributors to grasp instead.

The Dockerfile does not seem to work and I don't see anything referring to it / using it. In #1395 however there is now a Dockerfile that works nicely.

Yes, I see that there is .deb and AppImage prebuild in the release and available for download, but I want to build them from scratch myself as I want to play around with doing code changes and seeing the results in action. If I come up with something cool I might contribute JS changes. For now I am just trying to clean up the contributor documentation a bit.

[DeeDeeG]

A Docker employee contributed the Dockerfile way back in the Atom days, and I feel (given lack of any other obvious reason) it was merged out of politeness or "isn't that neat" factor, and "in case someone finds it interesting/useful..." but it was never a primary method for building nor an actually supported thing AFAICT. At best it was a potential replacement for the main/official build script at the time, but Atom folks never adopted it in that way; they never went beyond merging the file, and (for some reason, maybe again out of politeness or "in case useful to anyone" factor) accepting various update PRs later on from community members, achieving ambiguous (and diverging) goals, if any.

I'd like to yeet it because it is unsupported, and people reasonably assume it's supported or at least maintained, but it's not.

atom/atom#3925

[DeeDeeG]

There are also a .cirrus.yml file with build commands, and a Dockerfile with dependency lists, but seems to be nothing is using these. The Dockerfile is based on Ubuntu 20.04 but the GitHub Actions is running on Ubuntu 25.10, so probably nobody has used the Dockerfile for a long time.

Indeed the Dockerfile is not used and should IMO be removed.

We do run GitHub Actions and Cirrus routinely. The .cirrus.yml and .github/workflows/build.yml are the up-to-date CI files for the repository, for building the binaries we release. They are actively maintained and in current use.

(At the moment GitHub Actions produces our x86_64 binaries, and Cirrus produces our ARM64 binaries.)

[DeeDeeG]

The CONTRIBUTING.md doc section Local development simply refers to https://flight-manual.atom.io/ which does not exist anymore.

The whole CONTRIBUTING.md appears to be mostly legacy info from the time we forked from Atom, and sadly out of date. :[ It'd be well worth updating that for sure.

why Libsecret is needed

Likely for the bundled github package, which can store a PAT to authenticate users to github.com for integrations with issues, PR's, pulling/pushing commits to repositories (including potentially private ones), etc. Besides ppm using it to store credentials for publishing to the Pulsar package registry, and for starring / unstarring Pulsar packages.

I vaguely recall Chromium itself prompts for a password to protect your site logins?... something not really relevant for us, since Pulsar is not meant to be easy to use to browse arbitrary web pages -- it opens your real browser to follow links.

what NodeJS version is needed

In my personal understanding, we tried to be buildable on multiple recent-ish Node LTS versions... but our deps sometimes keep us stuck on older Node. And sometimes we leap forward after catching up with some of the technical debt. It is a bit of a moving target.

That said, it could indeed be nice to further document (or update the docs for) the current state of requirements.

[leotada]

I was another dev who tried once to build this project reading the docs and it didn't work. We need to at least be able to build to contribute.

[savetheclocktower]

I can definitely update Building Pulsar to reflect build instructions that work for me personally. Expect a PR in the next day or two.

[ottok]

@leotada Note that #1395 includes a Containerfile so you can easily run the whole dev environment in a container, or you can copy-paste the commands locally to have a fully working setup that is up-to-date with current 'master' branch contents.

[savetheclocktower]

I just took a quick pass on rewriting the docs and I'll open a PR soon, but it didn't seem to be vastly different from what the current guidance is. @leotada, do you recall what exactly didn't work?

[leotada]

@savetheclocktower I tried again using Fedora and when running yarn install command broke:

• wayland-client.h not found
• xkbccommon.h not found
  I resolved installing libxkbcommon-devel and wayland-devel packages, but then I had other compilling error:

What OS do you use generally?

[savetheclocktower]

Oof, that's not great. My upcoming PR will address the new dependencies on Wayland and XKB packages, but I've not seen that issue with fuzzy-native before.

I use macOS, as does @DeeDeeG. @confused-Techie uses Windows and @mauricioszabo uses Linux, though not Fedora. Maybe @mauricioszabo recognizes this error as he's a bit of a subject-matter expert on fuzzy-native as well.

My suspicion is that the binding.gyp of fuzzy-native might need some tweaking, but I'm not sure. It's a bit tricky for me to get Linux VMs running on an Apple Silicon chip, but I'll see if I can find an ARM Fedora image out there.

[savetheclocktower]

@leotada, I found the issue and opened fuzzy-native#8.

As that issue states, I was able to work around it with

export CXXFLAGS="-include cstdint"

and then re-running yarn install, but I'll make sure this gets fixed in fuzzy-native itself. Thanks for the feedback!

[savetheclocktower]

Also, I've confirmed that the current guidance is inaccurate regarding building for specific output targets; for instance, yarn dist targz doesn't work for just building the .tar.gz target. This is easy enough to add to the build script, so I've opened a PR for this.

[ottok]

In addition to documenting all buildtime dependencies in https://github.com/pulsar-edit/pulsar/pull/1395/files#diff-75c2b1fceb565d09588af47ddab567f69ba409731750c7fe732a83a17960b94cR12-R36 and runtime dependencies in https://github.com/pulsar-edit/pulsar/pull/1395/files#diff-c71dc00f55f3879b8390bda5a054d88a61723343cd20f3518a895ea0a7ddf85bR12-R47
I now documented all dependencies even more in detail in #1398 while looking into if I can make a Snap package for Pulsar. Comments welcome in those two PRs if you think I have misunderstood or found the wrong dependencies in the context of Debian/Ubuntu, Node 20 and Electron 30.