Hacking on Atom Core

Sometimes we need to upstream changes to Atom itself, so it is important to know how to work on it.

Fortunately, working on Atom core has a fast edit/refresh cycle just like hacking on Atom itself if you have it set up correctly.

First, you must clone the Atom repo, which you have probably already done:

git clone [email protected]:atom/atom.git ~/atom

Then you have to create a symlink to it from ~/github/atom (or set your ATOM_DEV_RESOURCE_PATH environment variable to ~/atom):

mkdir ~/github
ln -s ~/atom ~/github/atom

And then start Atom in development mode using the --dev flag:

atom --dev

From here, Atom will load its code from ~/atom/src/, so you can edit the .coffee files in place and use ctrl-alt-cmd-l to reload, just like you do for ordinary package development. This is much faster than running ~/atom/src/script/build after every edit to pick up your changes.

Some core packages (such as text-buffer) will have been provisioned into the atom/node_modules when Atom was built. If you want to work on those, the steps above will not be sufficient because --dev mode does not affect what is under Atom's node_modules directory. You should clone the corresponding public repo for the Atom package, run npm install, and then apm link [--dev] once to use a local version of the package. When you are done iterating on the package, be sure to run apm unlink [--dev].

IMPORTANT: You can get unwittingly stuck in dev mode, due to the problem described https://github.com/atom/atom/issues/6644. For now, you can get out of dev mode by closing all Atom workspaces, then opening a new workspace via File > New Window.

IMPORTANT: Currently (July 2015) Atom takes an absurdly long time to load packages in ~/.atom/packages in dev mode. It is recommended you clear out that directory if you're working in Atom Core.

---

NOTE: The instructions below are a work-in-progress.

Hacking on built-in packages

These are things like status-bar and tabs.

$ git clone [email protected]:atom/status-bar.git
$ cd status-bar
$ npm install
$ apm link

Hacking on Atom source and core modules

These are things in Atom's src like src/panel.coffee and src/text-editor.coffe. And Atom's modules like text-buffer and node-git.

Option 1: Work against /Applications/Atom.app's Electron

$ git clone [email protected]:atom/atom.git
$ cd ~/atom
# checkout the same version as your `/Applications/Atom.app`
$ git checkout v1.6.0
# only download and install deps (no need to create App bundle)
$ node script/bootstrap
# Symlink whatever module you're going to work on....
# QUIT ATOM, then
$ atom -r ~/atom

Option 2: Work against the revision's Electron

$ git clone [email protected]:atom/atom.git
$ cd ~/atom
# build Atom but don't install it
$ script/build --no-install
# Symlink whatever module you're going to work on....
# QUIT ATOM, then
$ ATOM_PATH=~/atom/out atom -r ~/atom

If you have the source in ~/github/atom, then you may skip the -r flag and instead use --dev.