[Step 0: have all the build requirements listed in "Hacking on Atom Core". Particularly: Node and npm, and a Python 2.6, 2.7 or 3.5+ executable, on your system PATH. Various packages are needed, including for Linux g++ and gcc (there is a longer list at Hacking on Atom Core), for macOS you need XCode or the "command line tools" package, for Windows you need a valid install of Visual Studio/Visual Studio Build Tools with the right plugins. Recommend getting it via installing the windows-build-tools npm package globally, as described in "Hacking on Atom Core."]
git clone https://github.com/atom/atom
cd atom
script/build
(Note about building installers on Windows or Linux: If you're on Windows and want to make an installer .exe, then run with script/build --create-windows-installer. If you're on Linux and want to make a .deb package, run with script/build --create-debian-package, and if you want to make a .rpm package, run with script/build --create-rpm-package. on macOS, there is no special installer needed. The built "out/Atom.app" can be dragged to the Applications folder if installing it to the system is desired.)
script/build bootstraps the scripts and dependencies and then builds Atom in the out/ folder.
After running script/build, you can find the Atom executable in out/ and run Atom.
- on macOS, on the command-line, to run Atom, it's:
out/Atom\ Dev.app/Contents/MacOS/Atom\ Dev, but in Finder you would simply double-click "out/Atom Dev.app". - on Linux, it's
out/atom-dev-[version number such as "1.56.0"]-dev-[commit hash]-[arch, such as "amd64"]/atom - On Windows, it's
out\Atom Dev [arch, such as "x64"]\atom-dev.exe
Okay. At this point, we have a fully built Atom. It bundles and contains the state of the repo as it was on upstream's master branch.
Say we make some changes in the core app. There are essentially two ways of running these changes in Atom.
The conceptually simplest way to get an updated Atom, is to build Atom again.
(Note: If you want to preserve your existing build before rebuilding, you can move or rename the out folder you already built. (I personally have a habit of renaming these as out-[some identifying info or feature for this build]. Then I add out-* to a line in my .gitignore file to avoid it slowing down my git operations scanning through so many files.)
Then, if you haven't changed any packages in Atom's core (the main node_modules folder in the repository), then you can skip bootstrapping. Do that with script/build --no-bootstrap.
If you have updated some packages with native code, be sure they are built against the right version of Electron. (Not built against an old version of Electron, built against Node, or installed without native code built at all...).
apm is purpose-made to build native code against Electron.
First, tell apm where to find the Atom repo's package.json metadata, by doing export ATOM_RESOURCE_PATH=/Users/[you]/path/to/atom on macOS, export /home/[you]/path/to/atom on Linux, or set ATOM_RESOURCE_PATH=C:\Users\[you]\path\to\atom on Windows. This step is necessary to make sure apm builds code against the correct version of Electron, based on the electronVersion field in the Atom repo's package.json.
Confirm that you have set this variable correctly: Run [path/to/]apm --version and see if the atom version matches the version you are developing in the Atom git repo. For example, this might be part of the apm --version output: atom 1.56.0-dev
Now, make sure you are cd'd to the root of the Atom repo where we want to rebuild our packages.
To use the Atom repo's included apm, do ./apm/node_modules/.bin/apm rebuild. To use an apm installed to your PATH, simply do apm rebuild. This rebuild command only rebuilds native code in installed packages, but doesn't add, remove or otherwise update any packages.
For a more comprehensive rebuild, see the next paragraph:
If you're really not sure what you have in the main node_modules folder, and if you want to be certain that they match what's specified in package.json and package-lock.json, you can totally reinstall with a clean slate, with ./apm/node_modules/bin/apm ci. This will take longer than just rebuilding the native code, but it is a good fallback option if the packages seem broken or incorrectly installed in your built Atom, or if script/build or launching in Dev Mode fails.
Every Atom executable has the power to load most of its files from an arbitrary location on disk. This is known as Dev Mode. There are several ways to activate Dev Mode.
(Note: Loading a new window in Dev Mode is slow. If Atom is already open in Dev Mode, and you want to quickly reload the changes you made to the Atom repository, you can reload the window. Use the menu "View" --> "Developer" --> "Reload Window". There will be a keyboard shortcut listed there in the menu as well, if you prefer keyboard shortcuts.)
The most explicit way is to run Atom with the --resource-path flag (or -r for short). The --resource-path flag lets Atom know where to load files from. (If the --resource-path flag is set, --dev is also set, internally.)
Examples:
- Linux:
/usr/share/atom/atom --resource-path /home/[me]/atom - macOS:
/Applications/Atom.app/Contents/MacOS/Atom --resource-path /Users/[me]/atom. - Windows:
C:\Users\[me]\AppData\Local\atom\app-[version]\atom.exe --resource-path C:\Users\[me]\atom
Another way is to simply have your Atom repository cloned to the expected location, which is hard-coded into Atom. The default location is calculated as a path relative to the current user's home directory; It is [your home directory]/github/atom... If your Atom repo is cloned there, simply start Atom with the --dev flag. Atom should look in the default location, see your files, and load them.
A third way is to export (on Linux and macOS) or set (Windows) an environment variable ATOM_DEV_RESOURCE_PATH. If this environment variable is set to the absolute path of your Atom repository, then Atom will look there when run with --dev. Atom will see the files there and load them. Example: export ATOM_DEV_RESOURCE_PATH=/home/[me]/atom (Linux/macOS). Or set ATOM_DEV_RESOURCE_PATH=C:\Users\[me]\atom (Windows).
(Note: You may want to add this export ATOM_DEV_RESOURCE_PATH=[the/path...] to the bottom of your shell profile (for macOS and Linux), such as ~/.bashrc or ~/.zshrc. Or on Windows, run SystemPropertiesAdvanced.exe from the command-line and set the variable there. (Tutorial). This will make the location persistent so you can conveniently run Atom in --dev mode any time and load your changes as expected.)
Launch any Atom app. From the Atom app, go to the menu, and select "View" --> "Developer" --> "Open In Dev Mode...", then select the location of your Atom repository on the disk. This will open a new Window that is in Dev Mode running the code from the Atom repository you selected.
When you're ready to publish changes, or if you want to get someone else's changes, consider setting up additional "remotes" in your cloned Atom repository.
To add your own fork as a remote, do the following:
git remote add [my_username] https://github.com/[my_username]/atom
git remote update [my_username]
Then you can push to that remote:
git push [my_username] HEAD:[target_branch_name_at_your_fork]
Or even better, set up the local branch to track the remote branch:
git branch --set-upstream-to=[my_username]/[remote_branch_name]
Or switch to/track a remote branch:
git switch --track [my_username]/[remote_branch_name]
To push committed changes when already tracking a remote branch, simply do:
git push
You can fetch a specific pull request branch, by doing this:
git fetch git@github.com:atom/atom.git refs/pull/[PR_#_HERE]/head
git switch -c [new_branch_name] FETCH_HEAD
(Based on a StackOverflow answer: https://stackoverflow.com/a/9903203)
Create a new branch from wherever you are:
git switch -c [new_branch_name]
Switch to a branch you've already checkout, or with a name that only exists at one of your remotes:
git switch [any_branch_name]