Atom Deployment and Usage Guide

⚠️ Project Status: Atom and all repositories under Atom were archived on December 15, 2022. This guide is preserved for historical reference and maintenance of existing installations.

1. Prerequisites

Required Tools

• Git — Required for cloning and package management
• Node.js — Runtime for building from source (version compatible with Electron)
• Python — Required for compiling native Node.js modules (2.7 or 3.x)
• C++ Toolchain — Platform-specific compiler for native dependencies:
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Windows: Visual Studio Build Tools or Visual C++ Redistributable
  • Linux: build-essential, gcc, g++, make

Linux System Dependencies

For 64-bit Linux systems, install these libraries before running or building:

sudo apt install git libasound2 libcurl4 libgbm1 libgcrypt20 libgtk-3-0 \
  libnotify4 libnss3 libglib2.0-bin xdg-utils libx11-xcb1 libxcb-dri3-0 \
  libxss1 libxtst6 libxkbfile1

2. Installation

Option A: Prebuilt Binaries (Recommended)

Since the project is archived, use existing releases:

macOS

1. Download atom-mac.zip or atom-mac-symbols.zip from the releases page
2. Extract and move Atom.app to /Applications

Windows

1. Download AtomSetup.exe (32-bit) or AtomSetup-x64.exe (64-bit)
2. Run the installer
3. Alternatively, use Chocolatey: cinst Atom

Linux

1. Download atom-amd64.deb (Debian/Ubuntu) or atom.x86_64.rpm (Fedora/RHEL)
2. Install via package manager, or extract atom-amd64.tar.gz for portable usage:

   tar xf atom-amd64.tar.gz
   ./atom/atom  # Launch from extracted directory
   

Option B: Build from Source

# Clone the repository
git clone https://github.com/atom/atom.git
cd atom

# Checkout specific version (optional)
git checkout v1.60.0  # Last stable version

# Install dependencies and build
script/bootstrap
script/build

# Create distributable package
script/build --create-debian-package  # Linux
script/build --create-mac-package     # macOS
script/build --create-windows-installer # Windows

3. Configuration

Configuration Files

Atom uses CSON (CoffeeScript Object Notation) for configuration:

• User Config: ~/.atom/config.cson (or %USERPROFILE%\.atom\config.cson on Windows)
• Init Script: ~/.atom/init.coffee or ~/.atom/init.js — Runs on startup
• Keymap: ~/.atom/keymap.cson — Custom keyboard shortcuts
• Snippets: ~/.atom/snippets.cson — Code snippets
• Stylesheet: ~/.atom/styles.less — Custom CSS

Environment Variables

# Development mode (loads packages from ~/.atom/dev/packages)
export ATOM_DEV_RESOURCE_PATH=/path/to/atom/source

# Disable GPU acceleration (troubleshooting)
export ATOM_DISABLE_GPU=1

# Use specific Node.js for building
export ATOM_NODE_VERSION=16.0.0

Package Management

Install packages via CLI:

apm install <package-name>      # Install package
apm install --check             # Verify native module dependencies
apm publish <version>           # Publish package (requires GitHub API token)

4. Build & Run

Development Mode

# Run from source without installing
script/run

# Or with specific options
script/run --dev --foreground --enable-electron-logging

Production Build

# Clean previous builds
script/clean

# Full build (downloads dependencies, compiles native modules, builds application)
script/build

# Output locations:
# - macOS: out/Atom.app
# - Linux: out/atom-<version>-amd64
# - Windows: out/Atom<version>

Running Tests

script/test  # Run full test suite

5. Deployment

Desktop Distribution

Since Atom is a desktop Electron application, "deployment" means creating installable packages:

Create Platform Packages:

# macOS (.dmg)
script/build --create-mac-package --code-sign --compress-artifacts

# Windows (.exe installer)
script/build --create-windows-installer --code-sign

# Linux (.deb)
script/build --create-debian-package

# Linux (.rpm)
script/build --create-rpm-package

Silent/Enterprise Installation

Windows:

AtomSetup.exe --silent

macOS:

# Copy to Applications via script
cp -R Atom.app /Applications/
xattr -dr com.apple.quarantine /Applications/Atom.app  # Remove quarantine attribute

Linux:

# Debian/Ubuntu unattended
sudo dpkg -i atom-amd64.deb
sudo apt-get install -f  # Fix dependencies

Portable Installation

Extract the .tar.gz (Linux) or .zip (Windows) to a user-writable directory. Atom will store its configuration in the extraction directory if you create a .atom folder there before first launch.

6. Troubleshooting

Build Failures

Error: gyp failed with exit code 1

• Cause: Python or C++ compiler not found
• Solution: Ensure Python is in PATH (which python or where python) and build tools are installed

Error: npm ERR! code ELIFECYCLE during bootstrap

• Cause: Node version incompatible with archived Electron version
• Solution: Use Node 14.x or 16.x (check package.json engines field)

Runtime Issues

Linux: error while loading shared libraries

• Cause: Missing system dependencies
• Solution: Install the apt dependencies listed in Prerequisites section

Linux: Atom window is blank/white

• Cause: GPU acceleration incompatibility
• Solution: Launch with atom --disable-gpu or set ATOM_DISABLE_GPU=1

Windows: Atom crashes on startup

• Cause: Corrupted GPU cache or incompatible graphics drivers
• Solution: Delete %USERPROFILE%\.atom\gpu-cache and restart

macOS: "Atom" cannot be opened because the developer cannot be verified

• Cause: Gatekeeper blocking unsigned app (archived project)
• Solution: xattr -cr /Applications/Atom.app or right-click > Open

Package Management

apm install fails with native module errors

# Rebuild native modules for current Node version
apm rebuild

# Or force rebuild with specific Node headers
npm rebuild --runtime=electron --target=11.0.0 --disturl=https://atom.io/download/electron

Slow startup

• Diagnosis: Run atom --profile-startup to identify slow packages
• Solution: Disable packages in Settings > Packages or remove from ~/.atom/packages/

Archive-Specific Notes

Since Atom is archived:

• Automatic updates no longer function (disable in Settings)
• Package registry (atom.io/packages) may become unavailable; install packages from local .git repositories or GitHub tarballs:

  apm install user/repo