Merge pull request circleci#1759 from circleci/macos

Add reference for macOS executor syntax

Author: michelle-luna

jekyll/_cci2/configuration-reference.md

@@ -52,6 +52,7 @@ Key | Required | Type | Description
 ----|-----------|------|------------
 docker | Y <sup>(1)</sup> | List | Options for [docker executor](#docker)
 machine | Y <sup>(1)</sup> | Map | Options for [machine executor](#machine)
+macos | Y <sup>(1)</sup> | Map | Options for [macOS executor](#macos)
 shell | N | String | Shell to use for execution command in all steps. Can be overridden by `shell` in each step (default: See [Default Shell Options](#default-shell-options))
 steps | Y | List | A list of [steps](#steps) to be performed
 working_directory | N | String | In which directory to run the steps. (default: `~/project`. `project` is a literal string, not the name of the project.) You can also refer the directory with `$CIRCLE_WORKING_DIRECTORY` environment variable.
@@ -92,7 +93,7 @@ jobs:
       - run: make
 ```
 
-#### **`docker`** | **`machine`** (_executor_)
+#### **`docker`** / **`machine`** / **`macos`**(_executor_)
 
 An "executor" is roughly "a place where steps occur". CircleCI 2.0 can build the necessary environment by launching as many docker containers as needed at once, or it can use a full virtual machine. Learn more about [different executors]({{ site.baseurl }}/2.0/executor-types/).
 
@@ -222,6 +223,27 @@ jobs:
       image: circleci/classic:201708-01
 ```
 
+
+#### **`macos`**
+{:.no_toc}
+
+CircleCI supports running jobs on [macOS](https://developer.apple.com/macos/), to allow you to build, test, and deploy apps for macOS, [iOS](https://developer.apple.com/ios/), [tvOS](https://developer.apple.com/tvos/) and [watchOS](https://developer.apple.com/watchos/). To run a job in a macOS virtual machine, you must add the `macos` key to the top-level configuration for the job.
+
+Key | Required | Type | Description
+----|-----------|------|------------
+xcode | Y | String | The version of Xcode that is installed on the virtual machine.
+{: class="table table-striped"}
+
+
+**Example:** Use a macOS virtual machine with Xcode version `9.0`:
+
+```YAML
+jobs:
+  build:
+    macos:
+      xcode: "9.0"
+```
+
 #### **`branches`**
 
 Defines rules for whitelisting/blacklisting execution of some branches if Workflows are **not** configured. If you are using Workflows, job-level branches will be ignored and must be configured in the Workflows section of your `config.yml` file. See the [workflows](#workflows) section for details. The job-level `branch` key takes a map:

jekyll/_cci2/executor-types.md

@@ -14,9 +14,9 @@ This document describes images and containers in the following sections:
 {:toc}
 
 ## Overview
-This version of CircleCI enables you to use Docker images or to use a dedicated VM image. 
+This version of CircleCI enables you to run jobs in one of three environments: using  Docker images, using a dedicated Linux VM image, or using a macOS VM image.
 
-There are tradeoffs to `docker` versus `machine`, as follows:
+For building on Linux, there are tradeoffs to `docker` versus `machine`, as follows:
 
 Virtual Environment | `docker` | `machine`
 ----------|----------|----------
@@ -81,6 +81,22 @@ jobs:
 
 The images have common language tools preinstalled. Refer to the [specification script for the VM](https://raw.githubusercontent.com/circleci/image-builder/picard-vm-image/provision.sh) for more information about additional tools.
 
+### Using macOS
+
+Using the `macos` executor allows you to run your build in a VM running macOS with a specific version of Xcode installed.
+
+```
+jobs:
+  build:
+    macos:
+      xcode: "9.0"
+      
+    steps:
+      # Commands will execute in macOS container
+      # with Xcode 9.0 installed
+      - run: xcodebuild -version
+```
+
 ## Using Multiple Docker Images
 It is possible to specify multiple images for your job. Specify multiple images if, for example, you need to use a database for your tests or for some other required service. **In a multi-image configuration job, all steps are executed in the container created by the first image listed**. All containers run in a common network and every exposed port will be available on `localhost` from a [primary container]({{ site.baseurl }}/2.0/glossary/#primary-container).