apeiron 0.9.0

Simple CLI for modpack management

=======
Apeiron
=======

*Утилита для управления модпаками*

.. image:: https://img.shields.io/pypi/pyversions/apeiron.svg
:target: https://pypi.python.org/pypi/apeiron
.. image:: https://img.shields.io/pypi/v/apeiron.svg
:target: https://pypi.python.org/pypi/apeiron
.. image:: https://coveralls.io/repos/github/Orhideous/apeiron/badge.svg?branch=master
:target: https://coveralls.io/github/Orhideous/apeiron?branch=master
.. image:: https://img.shields.io/travis/Orhideous/apeiron.svg
:target: https://travis-ci.org/Orhideous/apeiron
.. image:: https://pyup.io/repos/github/Orhideous/apeiron/shield.svg
:target: https://pyup.io/repos/github/Orhideous/apeiron/


Основные термины
----------------

- **Модпак** — совокупность файлов, которые могут быть доставлены
пользователю, сразу или после сборки
- **SourceManifest (SM)** — виртуальный объект исходников модпака,
описанный в ``index.yaml`` и представленный файлами в ``objects/``
- **TargetManifest (TM)** — виртуальный объект индекса и целевых файлов
модпака, доставляемых пользователю

Принцип работы
--------------

| Apeiron оперирует реконструированными из файлов виртуальными объектами
модпаков, предоставленными ``SM`` и/или ``TM``.
| Никакого другого хранилища метаданных, кроме самих файлов, нет.

| Все изменения в виртуальных объектах (например, создание ``TM`` из
``SM``, так называемый процесс сборки модпака) немедленно отображается в
ФС.
| Обратное тоже верно — любые изменения в файлах будут отображены
утилитой ``apeiron``

Статусы модпака
---------------

- **Fresh** — исходники модпака (``SM``) в точности равны собранным
файлам (``TM``)
- **Outdated** — ``TM`` не соответствует ``SM``, обычно, если файлы
исходников обновились
- **Not deployed** — для ``SM`` в модпаке пока не был собран ``TM``
- **Orphaned** — существует только ``TM`` в модпаке, без исходников
- **Broken** — нарушена целостность ``TM``, следует пересобрать или
удалить такой модпак
- **Unknown** — эфемерный модпак, запись в котором найдена в индексе,
стоит удалить его

Работа с ``apeiron``
--------------------

Для просмотра помощи по командам достаточно вызвать утилиту без
аргументов, ``apeiron``

Полный пример индекса исходников с комментариями
------------------------------------------------

.. code:: yaml

# Отображаемое имя модпака в лаунчере
title: Fancy pack with bells and whistles
# Внутреннее имя, используется в дальнейших операциях с модпаком
name: my_pack
# Версия игры
gameVersion: 1.10.2
# Список дополнительных флагов запуска, пустой по умолчанию
launch:
flags:
- -XX:SomeStrangeJavaFlag=42
- --debug
# Внутреннее версионирование, всегда 2
minimumVersion: 2
# URL к дополнительным библиотекам для этого модпака
# Добавляется к адресу по умолчанию в лаунчере
librariesLocation: http://libraries.devd.io
# Фактическое размещение файлов модпака, относительно индекса
objectsLocation: objects
# Список пользовательских файлов и каталогов, которые при установке
# модпака доставляются на клиент, но не перезаписываются при обновлении
userFiles:
include:
- options.txt
- config/MyAwesomeModStuff/*
# Список дополнительно загружаемых частей (DLC) модпака
features:
# Объект DLC
- properties:
# Внутреннее имя DLC
name: MoreBells
# Описание DLC
description: Adds extra bells!
# Рекомендован (starred) или нет (avoid) для загрузки
recommendation: starred
# Игнорируется, так как активно только на стороне клиента
selected: false
# Список файлов, входящих в DLС
files:
include:
- mods/MoreBells.jar
- mods/MoreBellsAddons*
- config/MoreBells.cfg

| Все пути на стороне утилиты должны рассматриваться относительно
каталога
| ``objects``, или же каталога игры на стороне клиента.

Конфигурация
------------

Для инициализации ``apeiron`` последовательно конфигурируется такими
файлами:

- ``/etc/config/apeiron.yaml``
- ``~/.config/apeiron.yaml``
Дополнительно, конфигурация, переданная через ``--config``, обновляет
уже загруженные значения.
Это полезно при работе с несколькими окружениями, см. ниже.

+---------------------+-------------------------+-------------------------------+
| Ключ | Значение по умолчанию | Описание |
+=====================+=========================+===============================+
| ``storage_dir`` | ``~/apeiron/storage`` | Рабочий каталог |
+---------------------+-------------------------+-------------------------------+
| ``modpack_index`` | ``index.json`` | Рабочий индекс модпаков |
+---------------------+-------------------------+-------------------------------+
| ``parallelism`` | ``12`` | Количеств рабочих процессов |
+---------------------+-------------------------+-------------------------------+

Работа с несколькими версиями окружений
---------------------------------------

| При необходимости разделить окружения (production/test) можно
использовать несколько индексов модпаков.
| Так, при вызове ``apeiron --config production.yaml`` и содержимом
``production.yaml``

.. code:: yaml

modpack_index: production.json

…все клиенты, для которых ``packageListUrl`` лаунчера будет указывать на
``production.json``, будут видеть только включенные там сборки.

Настройка веб-сервера
---------------------

Достаточно любого сервера, способного отдавать файлы с
``storage_dir/packages``

Пример для **nginx**, если ``storage_dir`` настроена в ``/opt/apeiron``:

::

server {
listen 80;
server_name packages.example.com;
root /opt/apeiron/packages;
}

Установка
---------

``pip3 install apeiron``

Системные требования
--------------------

- POSIX-совместимая ОС
- Python 3.6.1 и выше


Credits
-------

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage


=======
History
=======

0.9.0 (2018-09-01)
------------------

* First release on PyPI.