.. _macos:

Use of Breakout on macOS
========================

Newer versions of macOS won't allow binaries to execute if they are not from a
"trusted developer". This typically means, that the binary has to be signed. If
the downloaded binary is started either by double-clicking in the Finder or via
the CLI in a terminal, the following dialog can be seen:

.. image:: _static/bodoc_8.png
      :width: 532px
      :align: center
      :alt: warning dialog
      
The Breakout utility is not digitally signed (yet) and therefore, the following
steps need to be followed to allow the execution of the Breakout utility on
macOS:

1. After downloading, find the binary in the Finder 

2. Right-click on the binary and select "Open With" and then select 
   your preferred terminal application:

   .. image:: _static/bodoc_9.png
      :width: 800px
      :align: center
      :alt: Open with iTerm
   
   If none is showing in the list right away like shown above for iTerm, then
   select "Other..." and choose "Terminal.app" from the "Utilities" folder in
   "Applications". Also select "All applications" from the "Enable" list:

   .. image:: _static/bodoc_10.png
      :width: 800px
      :align: center
      :alt: Open with Terminal.app

3. In the following dialog you can now select "Open" to override the system security
   warning. Ensure the file you are opening is actually the binary downloaded from
   the CML :sup:`2` controller:

   .. image:: _static/bodoc_11.png
      :width: 532px
      :align: center
      :alt: Open with Terminal.app

The operating system "remembers" this override and from now on it's possible to
run the Breakout utility without going through additional security warnings /
pop-ups.
