README

*** Описание GIT-buildfarm ***

Схема взаимодействия:

 __________________________                          _________________________
|                          |                        |                         |
|      Git-repositary      |                        |        Build-Host       |
|__________________________|                        |_________________________|      ____________
       |                                                   |                        /            \
       |- <component> >-------< clone,pull,push >----------|-< <working tree> >--< (   checkout   )
       |- <component> >-------< clone,pull,push >----------|-< <working tree>       \____________/
       |- <bf> --------------------------------------------|-> <build farm building>
       |   ^                                               |
       ~   |                                               ~
           |
 __________|_______________
|                          |
|     BF development       |
|__________________________|


Сборочная система представляет собой:

- систему контроля версий git
- git-репозитарий с набором компонентов
- одну или несколько сборочных машин
- утилиту bf, производяую сборку компонтов,
  также хранящуюся в репозитории

* Установка системы контроля версий *

Система контроля версий git должна быть версии 1.5.x.y
Установлена с помощью пакета в штатное место /usr/bin,
либо собрана из исходников и установлена в каталог
/opt/git, при этом необходимо каталог /opt/git/bin 
добавить в PATH.

Скачать исходные тексты можно с сайта http://git.or.cz

Установка из исходников производится следующим образом:

# make prefix=/opt/git
# make prefix=/opt/git install

* Подготовка сборочной среды, для сборки утилиты bf *

Для сборки утилиты bf необходим компилятор языка
Objective Caml >= 3.12 и программа make.

* Установка утилиты bf *

Скачиваем исходники bf:

git clone https://github.com/caml-programmer/bf bf.git

Утилита git использует curl для скачивания файлов, 
поэтому необходимые пременные окружения также должны 
быть выставлены.

Переходим в катлог с исходными текстам и запускам сборку:

 $ cd bf.git
 $ ./configure [<prefix>]
 $ make
 $ su -c "make install"

Если не указать <prefix> установка будет производиться в каталог /usr.
Появятся следующие файлы:

/usr/bin/bf
/usr/bin/make-autologin
/usr/bin/ssh-copy-id

Смотрим что получилось:

$ ldd /usr/bin/bf
        linux-gate.so.1 =>  (0xb782c000)
        libm.so.6 => /lib/i386-linux-gnu/i686/cmov/libm.so.6 (0xb77eb000)
        libdl.so.2 => /lib/i386-linux-gnu/i686/cmov/libdl.so.2 (0xb77e7000)
        libc.so.6 => /lib/i386-linux-gnu/i686/cmov/libc.so.6 (0xb7689000)
        /lib/ld-linux.so.2 (0xb782d000)

Получилось хорошо, никаких лишних зависимостей.

* Использование утилиты bf *

Запуск утилиты bf без параметров выводит возможные варианты
использования:

Usage: bf (prepare|update|forward|[re]build|[re]install|status) <components>
   or: bf (prepare|update|forward|[re]build|[re]install|status) <component> [branch <branch> | tag <tag>]
   or: bf (prepare|update|forward|[re]build|[re]install|status) <composite> [<tag>]
   or: bf (diff|changelog) <composite> <tag-a> <tag-b> [compact]
   or: bf (diff|changelog) <specdir> <rev-a> <rev-b>
   or: bf review <composite> <since-date>
   or: bf pack <specdir> <version> <release>
   or: bf update <specdir> [lazy] [<version>] [<release>]
   or: bf upgrade <specdir> [lazy|complete|full] [<branch>]
   or: bf fork <specdir> <source-branch> <new-branch> [<single-rev-depth>]
   or: bf clone <ssh-user>@<ssh-host> <pkg-path> [overwrite|depends|packages]
   or: bf clone <specdir> [overwrite] [norec] [<ver> <rev>]
   or: bf link <pkg-path> [symlink]
   or: bf top <specdir>
   or: bf graph <specdir> [<ver> <rev>]
   or: bf basegraph <specdir> [hard|soft]
   or: bf tag <composite> <tag>
   or: bf make (build|install) [<name>]
   or: bf versions <pkgdir>
   or: bf search <commit-id>
   or: bf shell
   or: bf clean
   or: bf log
   or: bf tests

Где под <composite> подразумевается файл с определением функции composite,
на языке Scheme, возвращающий список компонентов, над которым необходимо 
произвести действия. Содержание этого файла может быть примерно следующим:

--------------------------------------------------
(define (composite)
  '((icu)
    (boost (tag "version/1.35"))
    (log4cpp)
    (cppunit)
    (openssl)
    (mod-ssl)
    (squid (branch "light") (package "web-cache"))
    (steel-collar (branch "polishing-stone"))))
--------------------------------------------------
Если branch или tag не указаны, то собирается HEAD 
из ветки master.

Если указан package, это значит этот компонент не нужно
включать в пакет текущего комопзита.

Технологический утилита bf представляет собой набор
функций, которые могут потребоваться для сборки
компонента со встроенным интерпретатором языка
Scheme (R5RS). Таким образом в каждом ветке
компонента в его корне должен хранится файл .bf-rules,
содрежащий алгоритм сборки и установки на языке Scheme.

Помимо стандартных функций Scheme, утилита bf предоставляет
следующие функции для работы:


(prepare-components "component1" ... "componentN")
выполняет git clean -d -x для каждого компонента

(build-components "component1" ... "componentN")
запускает последовательно сборочное правило каждого
компонента

(rebuild-components "component1" ... "componentN")
пересобирает ранее собранные компоненты, используется
для обхода механизмов фиксации статусов компонентов

(install-components "component1" ... "componentN")
выполняет инструкции по установке для каждого
компонента

(reinstall-components "component1" ... "componentN")
переустанавливает ранее установленные компоненты,
используется для обхода механизмов фиксации статусов
компонентов

(simple-configure "arg1" ... "argN")
выполняет команду configure arg1 ... argN  в каталоге компонента

(simple-make "arg1" ... "argN")
выполняет команду make в каталоге компонента

(simple-install  "arg1" ... "argN")
выполняет команду make install  arg1 ... argN в каталоге компонента

(export (NAME1 "value1") (NAME2 "value2") ...)
экспортирует переменные в локальное окружение компонента на момент сборки

(ac-configure (name1 "value1") (name2 ()) ...)
выполняет команду ./configure --name1=value1 --name2 ...

(make (target)? (NAME1 "value1") (NAME2 "value2") ...)
выполняет команду make <target> NAME1=value1 NAME2=value2 ...
или make NAME1=value1 NAME2=value2 ...

(update-make-params "updated.file" (NAME1 "value1") (NAME2 "value2") ...)
побновлеет все переданные параметры в заданном файле

(log-command "cmd" "arg1" ... "argN")
запускает команду на исполнение с аргументами

(path-concat "path1" ... "pathN")
производит формирование пути из нескольких частей

(string-concat "string1" "string2" ...)
аналог string-append, в принципе не нужен

(install-file "file" "directory")
инсталлирует файл в заданную директорию, если
директория не существует, она создается с 
правами 775

(read-directory "directory")
читает список файлов в директории

(with-dir "directory" (lambda ()))
выполнение lambda-функции в заданной
директории

(with-extension "extension" (lambda (file)))
выполнение действий над файлами с заданным
расширением в текущей директории

(file-exists "file")
проверка существования файла (директория является файлом)

(get-env "NAME")
получение значения заданной переменной окружения,
если переменная не задана, возвращается пустая строка

(read-command "command-with-args")
возращает результат выполнения команды в виде
списка строк

(current-directory)
возвражает текущую директорию

(uname)
возвращет результат выполнения команды uname

(arch)
возвращает результат выполнения команды arch

(remove-file "file1" ... "fileN")
удаляет заданные файлы

(move-file "file" "directory")
перемещает файл в директорию

(make-directory "dir1" ... "dirN")
создает заданные директории рекурсивно "mkdir -p ..."

(move-directory "dirsrc" "dirdst")
перемещает директорию

(remove-directory "directory")
удаляет заданную директорию

(create-symlink "src" "dst")
создает символьную ссылку

(create-link "src" "dst")
создает жесткую ссылку

(is-directory "dir")
проверка, является ли файл директорей

(write-file "path-to-file" "content")
записываем данные в файл, если файл уже
существовал, то все данные перезаписываются


Полный список функций всегда можно посмотреть
в исходных текстах в файле commands.ml


* Запуск сборки нового проекта *

Для этого необходимо выделить директорию
для сборки и прописать файл .bf-params,
в котором будут переопределены переменные,
используемые в процессе сборки.

Список переменных по-умолчанию можно получить
следующим образом:

$ grep ^set_param params.ml

set_param ~default:(Sys.getcwd()) "top-dir";;
set_param ~default:(Sys.getcwd()) "dev-dir";;
set_param ~default:"logs" "log-dir";;
set_param ~default:"git://localhost/" "git-url";;
set_param ~default:"bf" "component";;
set_param ~default:"branch" "label-type";;
set_param ~default:"master" "label";;
set_param ~default:"." "plugins-dir";;
set_param ~default:"false" "composite-mode";;
set_param ~default:(Sys.getcwd()) "start-dir";;
set_param ~default:"low" "log-level";; (* low,high *)
set_param ~default:"" "make-opts";;
set_param ~default:"localhost" "smtp-server";;
set_param ~default:"25" "smtp-port";;
set_param ~default:"bf message" "smtp-subject";;
set_param ~default:"bf" "smtp-from-name";;
set_param ~default:"bf@notify" "smtp-from-mail";;

Типичный .bf-params может выглядеть
следующим образом:

git-url ssh://git@wiki/users/git/projects http://caml.ru/repos
top-dir /opt/project
dev-dir /opt/devel
dest-dir /data/project-dest
log-level high
smtp-notify-email project@domain.ru
smtp-from-mail project@domain.ru
smtp-server smpt.domain.ru
pkg-storage pkg-storage.domain.ru
autopkg true


При этом переменная top-dir используется в файлах
.bf-rules как prefix, а dev-dir как место, куда
устанавливать ненужные для дальнейшей пакетизации
файлы (например файлы документации или заголовочные 
файлы).

Параметр make-opts добавляет опции при вызове
каждого make в .bf-rules. В многопроцессорных системах
удобно использовать опцию -j утилиты make.

Параметр log-level указывает выводить ли низкоуровневый
процесс сборки на консоль.

Параметр autopkg включает режим автоматической пересборки
компонентов, в случае отсутствия при пакетировании
необходимого файла .bf-list для какого-либо компонента.

Параметр plugins-dir указывает директорию, где
лежат плагины на языке Scheme, для того, чтобы
плагины подключились, там должен сушествовать
файл lib.scm, при этом плагины могут загружаться
в произвольном порядке и не должны быть
зависимы в этом плане друг от друга (для 
динамического языка Scheme это вроде не проблема).

Все параметры глобальные и нативно доступны в
.bf-rules, как переменные языка Scheme.

Для удобства написания правил в файлах .bf-rules
были заданы несколько предустановленных макросов
для export, ac-configure, make, update-make-params.
Варианты их использования можно посмотреть в файле
plugins/lib.scm

В дальнейшем макросы будут переписаны на рекурсивные, 
чтобы обрабатывать более разнообразные синтаксы,
например, когда пара значений и одно значение постоянно
чередуются в списке аргументов.



* Пакетирование *

Для сборки пакетов используется действие bf pack,
у которого три аргумента: specdir, version и release.

В настоящий момент поддреживается несколько версий формата specdir,
в частности 1 и 2.

Формат specdir версии 1:

Файл: hooks.scm - набор хуков, например:
(define (after-build host location pkgname)
  (let ((storage "root@host:/var/tmp"))
    (send-file-over-ssh
     (path-concat location pkgname) storage)
    (send-file-over-ssh
     (path-concat location pkgname) "user@192.168.13.12:/var/tmp")
    (send-message
     (string-append "Package " pkgname)
     (package-build-message host location pkgname storage)
     (map (lambda (goblin)
            (string-append goblin "@oper.nu"))
          '("masha" "roma" "choops")))))

Файл: rh.files - список файлов в формате RPM-spec, например
%topdir/bin/
%dir %topdir/var

Файл: rh.req  - скрипт, генерирующий зависимости, например:
#!/bin/bash
/usr/lib/rpm/find-requires \
| sed -e 's/BEGIN;.*//' \
| sed -e 's/perl.*//' \
| sed -e 's/cppunit.*//' \
| sed -e 's/libpcre.*//' \
| sed -e 's/^lib$//' \
| sed -e 's#/usr/bin/##'

Файл rh.spec - RPM-спецификация (набор используемых подстановочных символов можно посмотреть в функции rpmbuild в rules.ml)
Файл version - файл с номером версии, тут - 1.0

Формат specdir версии 2 (пример):

Файл <pack-branch>/composite:

(define (composite)
  '((pack           (branch "master"))
    ;; runtime
    (jdk            (branch "master"))
    (jre            (branch "master") (package "jet-jre"))
    ;; devel
    (ant 	    (branch "master"))
    (maven	    (branch "master"))

    ;; our libs
    (ngramm         (branch "boost") (package "jet-detect"))
    (ngramm-maps    (branch "boost") (package "jet-detect"))
    (file-ng        (branch "release-2") (package "jet-detect"))
    
    (traf-daemon (branch "master"))
    (nio-http-proxy (branch "devel2"))))

Файл <pack-branch>/depends:

(depends
 (linux ()
  ;; here pkg-names is symbols in case-insensitive mode
  (jet-skvt-core (= "1.0") (desc "Jet SKVT core"))
  (jet-jre (last "1.6.0.14") (desc "Jet JAVA package"))
  (jet-detect (last "1.0") (desc "Jet detect tools")))
 (sunos ()
  ;; here pkg-names is strings in case-sensitive mode
  ("JETDskvt-core" (= "1.0") (desc "Jet SKVT core"))
  ("JETDjre" (last "1.6.0.6") (desc "Jet JAVA package"))
  ("JETDdetect" (last "1.0") (desc "Jet detect tools"))))

Файл <pack-branch>/params:

summary SKVT-proxy
license Commercial
vendor Jet Infosystems
group Security
url http://www.jetsoft.ru
email skvt-support@jet.msk.su

Файл <pack-branch>/post-install
Файл <pack-branch>/pre-install
Файл <pack-branch>/pre-uninstall
Файл <pack-branch>/pre-update

Файл <pack-branch>/version

2.0

* Автоматическое обновление пакета *

Для автоматического обновления пакета
используется действие update применительно
к specdir, включая pack-branch. Например:

# bf update pack/jet-skvt-proxy/devel 1.0 12

Если не указать номер ревизии, то bf постарается
автоматический определить её номер исходя из
уже собранных на данной машине пакетов. При
этом поиск пакетов будет производится в текущем
каталоге. Если автоматические определение не
сработает из-за отсутствия пакетов bf
предложит интерактивно ввести номерю ревизии.
Ревизия всегда должна быть представлена целым
числом.

Указание или не указание версии работает
аналогично. Версия в отличии от ревизии
представляется внутри bf как строка, поэтому
может содержать различные символы (не только 
цифры).

* Автоматическая сборка набора пакетов *

В bf для создания набора пакетов используется
концепция метапакета, который не содержит
компонентов, за исключением быть может
специального metapkg-компонента, инсталлирующий
один пустой файлик (чтобы rpmbuild и
прочие утилиты сборки пакетов не ругались
на отстуствие файлов в пакете). Но
при этом в зависимости к метапакету жестко
прописываются версии и ревизии остальных
пакетов из набора. При этом между
собой остальные пакеты могут быть связаны только
на уровне версий и лишь где необходимо на уровне 
ревизий - чтобы была достаточная гибкость
при разработке и частичном обновлении пакетов.

Для создания набора пакетов используется
команда:

# bf upgrade <specdir> [lazy|complete|full] [<branch>]

Например:

# bf upgrade pack/jet-skvt-base/devel lazy

При этом bf начнет рекурсивно создавать все
необходимые пакеты, пока не создаст пакет с
именем jet-skvt-base.

Флаг lazy - говорит о том, что в случае
отсутствия изменений в компонентах, новую
версию пакета нет необходимости собирать.
Если его не указать, то пакеты будут
собираться независимо от того, были ли
какие-либо изменения в компонентах или
нет.

Флаг full - используется для полного
обновления (пересборки с новым номером версии)
всех пакетов в принудительном
порядке, даже если изменений для них
в репозиториях не зафиксировано.

Флаг complete - включает режим, при
котором обновляются только те пакеты,
в которых зафикированы изменения, а также
пакеты, рекурсивно зависимые от них.

Если не указывать никаких флагов, то
включается режим по-умолчанию, который
равносилен режиму complete, с одним
исключением - в режиме по-умолчанию
проверяется также состояние файловой
системы. То есть наличиее на ней
необходимого для комплектности сборки 
пакета, если он отсутствует, значит 
будет производится его сборка (без
обновления версии).

В процессе отработки этого действия
bf может переходить в интерактивный
режим и спрашивать: какую pack-branch
использовать для сборки того или иного
пакета, если этих веток более чем одна.
Для того чтобы этого не происходило,
ветку для пакетов можно задать дополнительно
при вызове команды.

* Клонирование существующего набора пакетов *

Для клонирования уже собраного набора пакетов
в bf используется команда:

# bf clone <ssh-user>@<ssh-host> <pkg-path> [overwrite]

При в этом pkg-path - задается путь к пакету на удаленном
сервере. Подразумевается, что остальные пакеты,
определенные в зависимостях находятся по тому же
адресу.

Если задан флаг overwrite - то уже созданные пакеты
заданных версий и ревизий будут пересоздаваться, в противном
случае будут создаваться только те пакеты, которые
в текущем каталоге ещё отсутствуют.

Клонирование можно осуществлять как на однотипных
архитектурах, так и различных. Но в качестве pkg-path
надо брать путь к rpm-метапакету (так как в bf пока
автоматическое вычисление зависимостей реализовано
только для RPM).

* Клонирование/сборка зафиксированного набора пакетов *

# bf clone <specdir> [overwrite] [norec] [<ver> <rev>]

При указании overwrite, bf будет повторно собирать
уже существующие пакеты.

При указании norec, bf будет собирать только пакет
верхнего уровня.

Если не указать конкретную версию и ревизию, то
собираться будет последняя зарегистрированная 
версия пакета верхнего уровня.

* Сборка самых свежих компонентов *

# bf top <specdir>

* Ветвление проектов *

Для этого используется комманда:

# bf fork <specdir> <source-branch> <new-branch> [<single-rev-depth>]

Где под <source-branch> и <new-branch> подразумеваются не ветки компонентов,
а ветки пакетов, которые формально располагаются в компоненте pack.git все
в одной ветке master, но в разных директориях. Например так:

jet-url-checker/2.3.2
jet-url-checker/2.3.2/pre-update
jet-url-checker/2.3.2/depends
jet-url-checker/2.3.2/rejects
jet-url-checker/2.3.2/release
jet-url-checker/2.3.2/composite
jet-url-checker/2.3.2/pre-install
jet-url-checker/2.3.2/pre-uninstall
jet-url-checker/2.3.2/post-install
jet-url-checker/2.3.2/params
jet-url-checker/2.3.2/version
jet-url-checker/devel
jet-url-checker/devel/pre-update
jet-url-checker/devel/depends
jet-url-checker/devel/rejects
jet-url-checker/devel/release
jet-url-checker/devel/composite
jet-url-checker/devel/pre-install
jet-url-checker/devel/pre-uninstall
jet-url-checker/devel/post-install
jet-url-checker/devel/params
jet-url-checker/devel/version
jet-detect/2.3.2
jet-detect/2.3.2/depends
jet-detect/2.3.2/rejects
jet-detect/2.3.2/release
jet-detect/2.3.2/composite
jet-detect/2.3.2/post-install
jet-detect/2.3.2/params
jet-detect/2.3.2/version
jet-detect/devel
jet-detect/devel/depends
jet-detect/devel/rejects
jet-detect/devel/release
jet-detect/devel/composite
jet-detect/devel/post-install
jet-detect/devel/params
jet-detect/devel/version

Перед использованием данной команды сперва стоит потренироваться в какой-нибудь
тестовом окружении, чтобы чётко уяснить, что она делает.

* Графическое представление дерева пакетов *

# bf graph <specdir> [<ver> <rev>]
# bf basegraph <specdir> [hard|soft]

Для работы этих действий потребуются установленные
утилиты dot(graphviz) и qiv.

* BF snapshot *

Сборка набора пакетов из указанных веток компонентов

# bf snapshot <specdir> [<composite>]

Данное действие обновляет все компоненты по заданным веткам и собирает все пакеты.
В качестве версии для всех пакетов используется дата, а в качестве ревизии - время
запуска bf snapshot.


* BF Scheme shell *

# bf shell

Позволяет протестировать работу встроенной R5RS Scheme,
иногда её работа отличается от поведения MzScheme (например
при использовании syntax-rules).

* SSH keys *

Для того чтобы успешно работала функция:

(send-file-over-ssh <local-source> <remote-destination>)

Необходмо подложить ssh ключи, например с помощью
утилиты make-autologin, входящей в поставку bf.

Запуск команды производим на машине, на которой должна
запускаться send-file-over-ssh:

 $ make-autologin user@host

Вводим правильный пароль и всё работает.