Skip to main content
The atlas run command builds your project and immediately executes it for local testing and development. This is the fastest way to iterate on your Atlas Engine application.

​
Usage

atlas run [OPTIONS]
Run this command from your project root directory (where atlas.toml is located).

​
Options

​
—release, -r

Build and run in release mode with optimizations enabled. 
atlas run --release
Values:
  • 0 - Debug build (default)
  • 1 or any non-zero value - Release build
Default: 0 (debug mode)

​
Build and Run Process

The run command performs the following steps:
1

Clean previous builds

Removes existing build/ and app/ directories to ensure a fresh build.
rm -rf build/ app/
2

Configure CMake

Sets up the build system with the appropriate configuration:
cmake .. -DCMAKE_BUILD_TYPE=Debug
3

Compile project

Builds your C++ application:
cmake --build . --config Debug
4

Execute application

Runs the compiled executable and displays output:
./build/bin/mygame

​
Example Output

​
Successful Run

$ atlas run
Packing project for target machine.
Using renderer: OpenGL
CMake configuration successful!
CMake build successful!
Executable found at: build/bin/mygame
[Application runs and displays window]
Application exited successfully.

​
Build Error

$ atlas run
Packing project for target machine.
Using renderer: OpenGL
CMake configuration successful!
CMake build failed!
[Error details displayed here]

​
Runtime Error

$ atlas run
Packing project for target machine.
Using renderer: OpenGL
CMake configuration successful!
CMake build successful!
Executable found at: build/bin/mygame
[Application runs but crashes]
Application exited with an error.

​
Development Workflow

The typical development cycle with atlas run:
1

Edit your code

Modify your C++ source files in your project directory:
// MyGame/main.cpp
void initialize(Window& window) override {
    // Add new game objects
    cube = createBox({2.0, 2.0, 2.0});
    window.addObject(&cube);
}
2

Run the project

Test your changes immediately:
atlas run
3

Observe results

Your application window opens automatically. Exit the app to return to the terminal.
4

Iterate

Repeat steps 1-3 until your application works as expected.

​
Debug vs Release Mode

​
Debug Mode (Default)

atlas run
Characteristics:
  • Faster compilation times
  • Includes debug symbols
  • No optimizations
  • Better for development and debugging
  • Larger executable size
Use when:
  • Developing new features
  • Debugging issues
  • Testing frequently

​
Release Mode

atlas run --release
Characteristics:
  • Slower compilation times
  • Optimized machine code
  • Smaller executable size
  • Better runtime performance
  • No debug symbols
Use when:
  • Testing final performance
  • Profiling your application
  • Verifying release builds

​
Platform Behavior

The run command works consistently across platforms:

​
macOS

Builds and runs the executable directly (not as a .app bundle): 
./build/bin/mygame

​
Linux

Builds and runs the native executable: 
./build/bin/mygame

​
Windows

Builds and runs the .exe file: 
.\build\bin\mygame.exe

​
Configuration

The run command respects platform restrictions from atlas.toml: 
[pack]
supported_platforms = "macos,linux"
If you run on an unsupported platform, you’ll see a warning but the build will continue: 
Current platform 'windows' is not supported for packing.

​
Troubleshooting

​
CMake Not Found

Failed to execute cmake command
Install CMake: 
# macOS
brew install cmake

# Ubuntu/Debian
sudo apt-get install cmake

# Windows
winget install Kitware.CMake

​
Missing Dependencies

CMake configuration failed!
Install required system libraries: 
# macOS
brew install glfw glm assimp freetype openal-soft

# Ubuntu/Debian
sudo apt-get install libglfw3-dev libglm-dev libassimp-dev \
  libfreetype6-dev libopenal-dev libgl1-mesa-dev

​
Compilation Errors

Check your C++ code for syntax errors. The full compiler output is displayed during the build. Common issues:
  • Missing semicolons
  • Undefined symbols
  • Incorrect include paths
  • Type mismatches

​
No Executable Found

No executable found in build directory.
This indicates the build failed. Check the CMake output for errors.

​
Application Crashes

Application exited with an error.
Your code compiled successfully but crashed at runtime. Debug by:
  1. Adding print statements
  2. Checking for null pointers
  3. Verifying resource paths
  4. Using a debugger like lldb or gdb

​
Resource Loading Errors

If your application can’t find assets: 
// The MAIN_PATH macro points to your project root
std::string assetPath = std::string(MAIN_PATH) + "/assets/texture.png";
Ensure assets are in the assets/ directory relative to your project root.

​
Quick Tips

  • Use atlas run frequently during development for rapid iteration
  • Switch to atlas run --release when testing performance
  • Use atlas pack only when ready to distribute
  • Check CMake output if builds fail
  • Exit your application properly to see success/failure status

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us