<commit_before>---
layout: documentation
tags: docs
---

# Overlays

You can activate settings, called "overlays", by passing them on the command line.

```bash
$ atbuild --use-overlay bar
```

This activates the settings for the overlay across all targets:

```clojure
(package
  :name "Foo"
  :overlays {
    :bar {
        :compile-options ["-D" "FOO"]
    }
  }
)
```

You can add as many overlays as you like: `atbuild --use-overlay bar --use-overlay baz`.  They are processed in order.

# Task-scoped overlays

You can also only apply an overlay to a particular task.  To do this:

```clojure
(package
  :name "Foo"
  :tasks {
    :foo {
      :overlays {
        :bar {
          :compile-options ["-D" "BAZ"]
        }
      }
    }
  }
)
```

Now when we build with `--use-overlay bar`, this will add `-D BAZ` to compile options for the `foo` task, but not for other tasks in our file.

# 'Always' overlay

We can use an overlay even when it was not specified on the CLI.  This way we can share common configuration options between several tasks.

```clojure
(package
  :name "Foo"
  :overlays {
    :optimized {
      :compile-options ["-Owholemodule"] ;;whole module optimization
    }
  }
  :tasks {
    :foo {
      :use-overlays ["optimized"] ;;apply to this task
    }
    :baz {
      :use-overlays ["optimized"] ;;apply to this task too
    }
  }
)
```

# Imported overlays

Overlays can be [imported](import.md).  This allows libraries to export required compile flags to clients.

```clojure
(package
   :name "Library"
   :overlays {
    :compile-linux {
      :compile-options ["-Xcc" "-fblocks"] ;; work around https://bugs.swift.org/browse/SR-397
    }
   }
)
```

```clojure
(package
   :name "Executable"
   :import ["Library.atpkg"]
   :tasks {
    :foo {
      :use-overlays ["Library.compile-linux"] ;;apply to this task
    }
)
```

# Required overlays
 
You can specify that an overlay must be applied to a task.

```clojure
(package
   :tasks {
    :foo {
        :required-overlays [["osx" "linux"] ["debug" "release"]] ;;at least one of osx/linux and one of debug/release must be applied
    }
)
```

# Built-in overlays

The following overlays are enabled automatically by atbuild.

| overlay                | enabled?           |
|------------------------|--------------------|
| atbuild.platform.osx   | Building for OSX   |
| atbuild.platform.mac   | Building for OSX   |
| atbuild.platform.linux | Building for Linux |
| atbuild.platform.ios   | Building for iOS   |
<commit_msg>Document at.xcode-emit overlay<commit_after>---
layout: documentation
tags: docs
---

# Overlays

You can activate settings, called "overlays", by passing them on the command line.

```bash
$ atbuild --use-overlay bar
```

This activates the settings for the overlay across all targets:

```clojure
(package
  :name "Foo"
  :overlays {
    :bar {
        :compile-options ["-D" "FOO"]
    }
  }
)
```

You can add as many overlays as you like: `atbuild --use-overlay bar --use-overlay baz`.  They are processed in order.

# Task-scoped overlays

You can also only apply an overlay to a particular task.  To do this:

```clojure
(package
  :name "Foo"
  :tasks {
    :foo {
      :overlays {
        :bar {
          :compile-options ["-D" "BAZ"]
        }
      }
    }
  }
)
```

Now when we build with `--use-overlay bar`, this will add `-D BAZ` to compile options for the `foo` task, but not for other tasks in our file.

# 'Always' overlay

We can use an overlay even when it was not specified on the CLI.  This way we can share common configuration options between several tasks.

```clojure
(package
  :name "Foo"
  :overlays {
    :optimized {
      :compile-options ["-Owholemodule"] ;;whole module optimization
    }
  }
  :tasks {
    :foo {
      :use-overlays ["optimized"] ;;apply to this task
    }
    :baz {
      :use-overlays ["optimized"] ;;apply to this task too
    }
  }
)
```

# Imported overlays

Overlays can be [imported](import.md).  This allows libraries to export required compile flags to clients.

```clojure
(package
   :name "Library"
   :overlays {
    :compile-linux {
      :compile-options ["-Xcc" "-fblocks"] ;; work around https://bugs.swift.org/browse/SR-397
    }
   }
)
```

```clojure
(package
   :name "Executable"
   :import ["Library.atpkg"]
   :tasks {
    :foo {
      :use-overlays ["Library.compile-linux"] ;;apply to this task
    }
)
```

# Required overlays
 
You can specify that an overlay must be applied to a task.

```clojure
(package
   :tasks {
    :foo {
        :required-overlays [["osx" "linux"] ["debug" "release"]] ;;at least one of osx/linux and one of debug/release must be applied
    }
)
```

# Built-in overlays

The following overlays are enabled automatically by AT tools.

| overlay                | enabled?           |
|------------------------|--------------------|
| atbuild.platform.osx   | Building for OSX   |
| atbuild.platform.mac   | Building for OSX   |
| atbuild.platform.linux | Building for Linux |
| atbuild.platform.ios   | Building for iOS   |
| at.xcode-emit          | The xcode-emit tool is emitting a project   |

{'fraction_non_alphanumeric': 0.1408780487804878, 'fraction_numerical': 0.0011707317073170731, 'mean_word_length': 2.5278733654507914, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5168902', 'n_tokens_mistral': 1734, 'n_tokens_neox': 1639, 'n_words': 559}