Mac Maker Spec Files
====================

`Spec` files are JSON files that contain a series of absolute paths, that tell `Mac Maker` where to find the Ansible configuration required to provision a Mac.

Spec files are how `Mac Maker` internally finds the resources bundled in a `Mac Maker Profile`.

Absolute paths are often machine specific, and for this reason and it's much simpler and more portable to use `folder` or `github` install sources for your profile.

.. toctree::
   spec/spec.json.spec.rst

=======================
Working With Spec Files
=======================

Generally `Mac Maker Profiles` conform to a specific structure, but `Spec` files allow you to break all conventions and point to whatever locations are convenient to you, with the caveat that you must use absolute paths.

- :ref:`Profile Details and Specification <profile-label>`

The one unusual `Spec` file JSON key, is `inventory`.  Ansible uses an `inventory <https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html>`_ file to manage the lists of hosts that it will connect to.  In `Mac Maker`'s traditional use case, it's always connecting to localhost- so the inventory file has hard coded preset content for this.  This content is always written to a file named "inventory" in the `profile_data_path` filesystem location.

Using a `spec` file, it's MIGHT be possible to configure Ansible to provision remote Macs, but this isn't the use case this project is solving.  There is substantial complexity involved in doing this securely however.  Consult the `Ansible documentation <https://docs.ansible.com/ansible/latest/user_guide/connection_details.html>`_ for more details if you wish to explore this avenue.

====================
An Example Spec File
====================

.. code-block:: json

  {
    "workspace_root_path": "/Volumes/USB/mac_maker/installer.workspace/osx-profile-development",
    "profile_data_path": "/Volumes/USB/mac_maker/installer.workspace/osx-profile-development/profile",
    "galaxy_requirements_file": "/Volumes/USB/mac_maker/installer.workspace/osx-profile-development/profile/requirements.yml",
    "playbook": "/Volumes/USB/mac_maker/installer.workspace/osx-profile-development/profile/install.yml",
    "roles_path": [
      "/Volumes/USB/mac_maker/installer.workspace/osx-profile-development/profile/roles"
    ],
    "collections_path": [
      "/Volumes/USB/mac_maker/installer.workspace/osx-profile-development/profile/collections"
    ],
    "inventory": "/Volumes/USB/mac_maker/installer.workspace/osx-profile-development/profile/inventory"
  }