Release 0.4.4 (2017-02-28)
==========================

Getting usage help with ``usage``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Утилита командной строки доработана, чтобы быть более дружелюбной к пользователю.
Вызов утилиты ``ram`` без параметров теперь выдает краткую справку по самым необходимым командам.
Команда ``ram usage`` позволяет получить краткую справку по использованию той или иной команды:

.. sourcecode:: console

    # ram usage setup
    setup: use unit to configure environment

      To use unit:

        $ ram setup <namepath>


На странице :ref:`Quick Start <getting-in-touch>` добавлены примеры использования этих команд.


Calling ``ram`` commands from python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

В новой версии фреймворка появилась возможность вызывать команды ``ram`` из питоновского кода.
При этом сделан упор на идентичность семантики вызовов, например следующая команда shell:

.. sourcecode:: console

    # ram setup ifconfig device=eth0

идентична следующему коду на python:

.. sourcecode:: pycon

    >>> import ram
    >>> ram.setup('ifconfig', 'device=eth0')

или:

.. sourcecode:: pycon

    >>> import ram
    >>> ram('setup', 'ifconfig', 'device=eth0')

Для реализации этой функциональности в ``ram`` реализована модель сервисов.

Более подробно об этом на странице :doc:`../concepts/services`.


Low level python interface to ``ram``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Упомянутый в предыдущей секции python-интерфейс для фреймворка ``ram`` является высокоуровневым.
Возвращаемые им объекты зависят от конкретного вызываемого сервиса.
Примерами возвращаемых объектов могут быть простые коллекции (списки, словари) или Watch-объекты.

Кроме этого, в новом фреймворке реализован низкоуровневый python-интерфейс.
Этот интерфейс предназначен для написания оберток к интерфейсу фреймворка, таких как утилита командной строки.

Более подробно об этом на странице :doc:`../concepts/services`.


Libraries interaction: merging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

В предыдущих версиях фреймворка была реализована концепция тегированных скриптов в составе конфигурационного юнита.
Например, конфигурационный юнит ``hostname`` может включать скрипт ``apply`` для применения настроек в общем случае и
скрипт ``apply.collectd`` для применения настроек в демоне `collectd`.
Т.к. демон `collectd` не является стандартной частью системы, скрипт для этого демона не включен в стандартную библиотеку.
Однако фреймворк предоставляет средства для расширения и взаимодействия библиотек поставляемых в разных пакетах.
Фактически файлы в составе одноименных юнитов из разных библиотек объединяются в один виртуальный юнит.
Т.о. для расширения стандартного юнита `hostname` необходимо создать отдельную библиотеку и
создать в ней юнит ``hostname`` включив в него только один файл - ``apply.collectd``.
Для просмотра списка файлов в составе виртуального юнита реализована команда ``ram which``:

.. sourcecode:: console

    # ram which hostname apply*
    /usr/lib/ram/hostname/apply
    /opt/my-appliance/lib/ram/hostname/apply.collectd
    # ram tweak trace on
    # ram apply hostname
    : /usr/lib/ram/hostname/apply  = 0
    : /opt/my-appliance/lib/ram/hostname/apply.collectd  = 0

На данный момент в фреймворке не реализовано какого-либо гарантированного разрешения конфликтов для файлов с одинаковым именем.

Более подробно о команде :doc:`which <../services/which>`.


P.S.: в предыдущих версиях фреймворка была реализована экспериментальная версия этой функциональности на основе кэша.
Кэш представлял собой временную файловую иерархию для объединения порций юнита из различных библиотек.
В новой версии разрешение путей происходит динамически и необходимости во временном кэше больше нет.

Команда ``ram cache`` в этой версии оставлена для совместимости.


Libraries interaction: probing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Иногда может возникнуть необходимость использовать библиотеку юнитов изначально расчитанную на применение в иной конфигурации.
Например, юнит конфигурации прокси (``proxywiz``) изначально разработан для конфигурации двух различных демонов -- ``daemos`` и ``phobos``.
При этом ``daemos`` конфигурируется основными скриптами юнита, а ``phobos`` тегированными.
При необходимости переиспользовать этот юнит в системе без ``daemos`` фреймворк будет генерировать ошибки и
не позволит сконфигурировать присутствующий в системе ``phobos``. Для решения этой проблемы реализован механизм пробинга.

С точки зрения разработчика интерфейс механизма заключается в добавлении соответствующего файла ``probe`` или ``probe.<daemon>``.
Файл должен быть исполняемым. В его задачи входит определение наличия того или иного демона в системе.
В случае если, скрипт присутствует и в результате его выполнения получен ненулевой код ошибки,
последующее выполнение скриптов ``query.<daemon>``, ``store.<daemon>`` и ``apply.<daemon>`` не производится.


Даже если в оригинальной поставке юнита не был реализован соответствующий скрипт ``probe``,
его можно реализовать в библиотеке-расширении используя механизмы описанные в предыдущем разделе.

Более подробно о команде :doc:`probe <../services/probe>`.


Namespaces
~~~~~~~~~~

Разрастание кодовой базы конфигурационных юнитов ведет к необходимости структурной организации библиотек.
С этой целью в этой версии фреймворка в экспериментальном режиме реализована поддержка иерархичных пространств имен.

Располагая юниты в иерархии директорий можно обращаться к ним по иерархическому пути, например:

.. sourcecode:: console

    # ram setup subsys1.component2.subcomponent

Более подробно об этом на странице :doc:`../concepts/namepath`.