**************************
IOC Template Cookiecutters
**************************

Caproto IOCs are easy to get started with and only require a single source code
file as shown in the many examples provided here.

For larger projecs, making a single caproto IOC into its own Python package
brings along some benefits:

1. Easily installed into a Python environment
2. Ability to add command-line hooks
3. Better structure - relatve imports
4. Add tests, documentation

To ease this process, caproto offers two "cookiecutter_" templates, one for
generating your IOC package and one for creating a startup script that can
be used by procServ, systemd, init.d, and so on.

IOC Cookiecutter
================

The cookiecutter_ is available in the caproto organization on GitHub.

The steps outlining an IOC creation are tersely shown here for a quick example.

Install cookiecutter
^^^^^^^^^^^^^^^^^^^^

.. code-block:: sh

  $ pip install cookiecutter

Use the cookiecutter
^^^^^^^^^^^^^^^^^^^^

.. code-block:: sh

  $ cookiecutter https://github.com/caproto/cookiecutter-caproto-ioc
  project_name [project_name]:
  github_repo_group [pcdshub]:
  repo_name [project_name]:
  default_prefix [SIM:]:
  author_name [SLAC National Accelerator Laboratory]:
  email []:
  folder_name [project_name]:
  import_name [project_name]:
  description [project_name]:
  Select license:
  1 - SLAC
  2 - BNL
  3 - MIT
  4 - BSD-3
  Choose from 1, 2, 3, 4 [1]:
  Select auto_git_setup:
  1 - no
  2 - yes
  Choose from 1, 2 [1]:
  git_remote_name [origin]:
  Select auto_doctr_setup:
  1 - no
  2 - yes
  Choose from 1, 2 [1]:
  Select use_x11_on_travis:
  1 - no
  2 - yes
  Choose from 1, 2 [1]:
  year [2020]:


Create a test environment
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: sh

  $ conda create -n my_test_env python=3.7
  $ conda activate my_test_env

Install the project in that environment
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: sh

  $ cd project_name
  $ pip install .

Run the IOC
^^^^^^^^^^^

.. code-block:: sh

  $ project_name --list-pvs
  [I 17:33:28.970       server:  133] Asyncio server starting up...
  [I 17:33:28.971       server:  146] Listening on 0.0.0.0:5064
  [I 17:33:28.972       server:  205] Server startup complete.
  [I 17:33:28.973       server:  207] PVs available:
      SIM:SampleValue
      SIM:SampleScanned
  This happens at IOC boot!
  Initial value was: 0.0
  Now it is: 0.1

  ^C
  [I 17:33:30.442       server:  212] Server task cancelled. Will shut down.
  [I 17:33:30.442       server:  222] Server exiting....

Alternatively:
^^^^^^^^^^^^^^

.. code-block:: sh

  $ python -m project_name --list-pvs

Build the docs:
^^^^^^^^^^^^^^^

.. code-block:: sh

  $ cd docs
  $ make html

Open them in your browser:
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: sh

  # (macOS)
  $ open build/html/index.html
  # (Linux)
  $ xdg-open build/html/index.html


Startup Script Cookiecutter
===========================

The startup_cookiecutter_ is available in the caproto organization on GitHub.

Before using this cookiecutter, you should already have a caproto-based IOC you
wish to create startup scripts for. Please consider starting with the
cookiecutter from the previous section.

With standard EPICS IOCs, the IOC supporting code tends to be reused many
times, with only a per-IOC startup script configuring which records get created
with what PV prefixes, device IP addresses, and so on.

This cookiecutter aims to do something similar - take your existing IOC source
code and easily template multiple instances of that IOC. Several key points
(and benefits in the author's opinion) of this method are:

1. Decoupling PVGroup source code from per-IOC settings.
2. A git submodule of the IOC source to specify a released (or unreleased)
   versino of the IOC source code.
3. An independent conda environment per IOC.

If you want to use your IOC with **procServ**, this is the cookiecutter for
you.

The steps outlining an IOC startup script creation are tersely shown here for a
quick example.

Install cookiecutter
^^^^^^^^^^^^^^^^^^^^

.. code-block:: sh

  $ pip install cookiecutter


Use the cookiecutter
^^^^^^^^^^^^^^^^^^^^

.. code-block:: sh

    $ cookiecutter https://github.com/pcdshub/cookiecutter-caproto-ioc-startup
    $ cd ioc-my-iocname

Customize any settings
^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: sh

    $ vim config.sh

Run the IOC
^^^^^^^^^^^

.. code-block:: sh

    $ ./st.cmd
    [I 17:33:28.970       server:  133] Asyncio server starting up...
    [I 17:33:28.971       server:  146] Listening on 0.0.0.0:5064
    [I 17:33:28.972       server:  205] Server startup complete.
    [I 17:33:28.973       server:  207] PVs available:
        SIM:SampleValue
        SIM:SampleScanned
    This happens at IOC boot!
    Initial value was: 0.0
    Now it is: 0.1

    ^C
    [I 17:33:30.442       server:  212] Server task cancelled. Will shut down.
    [I 17:33:30.442       server:  222] Server exiting....


.. _cookiecutter: https://github.com/caproto/cookiecutter-caproto-ioc
.. _startup_cookiecutter: https://github.com/caproto/cookiecutter-caproto-ioc-startup