Ruby Policy 2.0

Ruby Policy

Rules for ruby module and application packages

Introduction

Ruby and modularity

NOTE: To simplify link usage, they will be treated as for 2.6.1 ruby version.

The ruby language have the modularity feature begginging with the day-spring of its invention in 1993th, so if we have the core functions of ruby are placed into the libruby.so, are built-in part of the language, then ruby's standard library is modularized, and its modules are resided in the /usr/lib/ruby/ folder that has the interpreted modules inside the consequently named folders. For example: parser module is placed in the racc module:

   /usr/lib/ruby/racc/parser.rb

Inside the folder named as <arch>-<os>, there are some compiled parts for the respective modules, so 'cparse modules is placed in racc module:

   /usr/lib/ruby/x86_64-linux/racc/cparse.so

Therefore the when a side library (module) ought to be be used in ordinal ruby applications, then its library modules must be placed into the respective folders in /usr/lib/ruby/site_ruby/, and the last is the only place to reside libraries not from the ruby standard set.

The the modern context, which is valid for 2019, in order to deploy additional modules, the rubygems and bundler modules are used, which kind of the modules is called as gem (russian 'бисер), and the first of them previously treated as usual ruby side module. The rubygems has begun in 2009 Apr., bundler in four months last than rubygems in Aug the same year. In present, the pair of the gems is de-facto an de-jure the only dynamically working system of dependencies of ruby modules system.

In modern projects the ruby gem dependencies can be provided with two ways:

• via <gem>.gemspec;
• via Gemfile.

The .gemspec is the only file to declare dependencies for rubygems between the gems themselves. The dependencies in the file can be joined into two groups separately: runtime, and development, and the least can be used also to test the gem project.

The Gemfile is the file to define local dependencies (additionally to .gemspec) from the other gems. The project containing the Gemfile counkl not be exactly the gem, but it can be one of the modern ruby application type as: rails or sinatra application, ruby script application. The dependencies can be joined into various kinds of groups along the default one like production, development, test, assets etc. Based on the current environment and written in the Gemfile scheme, the bundler makes a decision itself, which the gems shall be loaded, and which must be hidden that leads to situation when explicit declaration to call a module from a gem will be avoided. For example it can be observed in rails application like chef or foreman, or script application opennebula.

Typical Gemfile can be found here.

Dependencies to ruby also can be defined in Gemfile or .gemspec.

Versioning

In the ruby and its packaging subsystem the semantic versioning approach is applied, in which the first number responds to the major modification in the module, saying when the API is changed. The second number - minor modification, for example when a new feature is added to the module, and the third number means the patch change.

Comparison to the previous policy

Strictly speaking the approach with dependencies search over the only require calls to the modern time is significantly restricted by the following points:

• this method calls are not always exactly detecting the real dependencies list for gems, and increasingly for Gemfile-based projects, insofar as there may be non-mandatory calls to require in the code, which are framed in the begin-end code that makes the call optional;
• for Gemfile-based projects the require calls are implicit and executed by bundler indirectly based on the Gemfile and .gemspec files analysis, if any, then bundler monitors for integrity of the current module development environment, this leads to that the require call to external module, in case the dependency to the module isn't declared in the Gemfile, will raises the module not found error that will block the project development (in case of rpm building to build error);
• a name of external module is not always can be inferred from analysis of require call lines, since some modules have non-standard naming in a relation to their gem, for example a gem can have name 'foo-bar', its modules can have FooBar, FooBar, или Foo/Bar, but correspondence to those files will have foo_bar, foo/bar, and the last is falsely triggered on foo module name;
• implicit loading of the external project modules, because bundler make the calls to that modules itself;
• technique for dependency detection from require isn't capable to control API-version of the dependent package, when it is changed, especially in case when the package requires old and non-updated API.

Thus, in modern times is it more safely to use Gemfile/.gemspec file pair analysis to determine the dependencies.

The 'ruby' package

In the system there is the only libruby library, with a single set of the stdlibs modules.

When a new version of the libruby package has been built, all the stdlibs modules is rebuilt also, along with all gems that contain dynamically loaded .so libraries that conforms to the new version of libruby, or where the Gemfile/.gemspec file pair contains explicit requirement to the ruby version in.

External view of package

1. packages that have been built from a gem, must have gem- prefix;
2. source packages containing the rails, sinatra or similar applications can be without a prefix or have rubyapp- prefix;
3. stdlibs modules along with other projects that don't belong to previous two points, and non-gem libraries must have ruby- prefix, and their files be placed into site_ruby folder;
4. underscore chars "_" are replaced to minus '-' char in the names of packages.

Зависимости

Зависимости теперь отслеживаются на основе анализа пары Gemfile/.gemspec.

Экспорт зависимостей на бисеры имеет вид gem(gemname) = version и rubygem(gemname) = version, для совместимости с пакетами rpm от redhat.

Конфликт зависимостей

В случае конфликта зависимостей применяются один из двух способов их разрешения:

• в случае сохранения работоспособности бисера следует применять схему с явным объявлением макроса подмены версии требуемой библиотеки, имеющим имя gem_replace_version, напр. с ~> 1.1.7 на ~> 1.7:

%gem_replace_version '~> 1.1.7' '~> 1.7'

• поскольку bundler позволяет хранить в одном и том же дереве бисеров несколько версий для каждого из них, а система альта такого не позволяет делать, требуется создание пакета совместимости версии, который будет содержать заполненную дефисами версию бисера без заплаточного числа (patch number), в дополнение к его имени, напр. такой бисер compat-gem будет иметь имя пакета: gem-compat-gem-1-2-1.2.0.src.rpm;

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

Макросы RPM

Макросы, требуемые для опакечивания бисеров и приложений руби, определены в rpm-, который советуем объявить в спецификации пакета в сборочном требовании в пометой (pre), так BuildRequires(pre): rpm-build-ruby:

Сборочные макросы таковы:

%__ruby                 %_bindir/ruby
%__setup_rb             %_bindir/setup.rb

%ruby_func()            %__ruby -rrubygems -rrbconfig -e %*
%ruby_rubyconf_func()   %__ruby -rrubygems -rrbconfig -e 'print RbConfig::CONFIG["%*"]'

%ruby_gemspecdir        %(%ruby_func 'print File.join( Gem.dir, "specifications" )')
%ruby_gemextdir         %(%ruby_func 'print File.join( Gem.dir, "extensions", RbConfig::CONFIG["sitearch"], RbConfig::CONFIG["ruby_version"] )')
%ruby_gemlibdir         %(%ruby_func 'print File.join( Gem.dir, "gems" )')
%ruby_ridir             %(%ruby_rubyconf_func ridir)

%gem_build              %__setup_rb build
%gem_install            %__setup_rb install --install_prefix=%buildroot
%gem_test               %__setup_rb test
%gem_show               %__setup_rb show --install_prefix=%buildroot

Расположение файлов

Файлы бисеров будут располагаться в соответствующих подпапках для бисеров папки /usr/lib/ruby/gems/2.5.0/, где 2.5.0 версия руби без учета заплаточного числа.

Заметки по спецификации пакета

1. также пакеты содержащие основной код бисера, должны иметь группу Development/Ruby. А пакеты содержащие исполняемый код из того или иного бисера, должны иметь группу соответствующую назначению пакета;
2. пакеты, не содержащие двоичного исполняемого кода модуля, должны содержать явное объявление архитектуры noarch.

Типовой .spec

Для исправления старых или сломанных пактов, а также создания новых можно использовать такой типовой файл спецификации:

%define   pkgname gemmodule
Name:     ruby-%pkgname
Version:  0.0.0
Release:  alt1
Summary:  summary
Group:    Development/Ruby
License:  <LICENSE>
URL:      https://site.org/
# VCS:    https://github.com/user/gemmodule.git
Source:   %pkgname-%version.tar

BuildRequires(pre): rpm-build-ruby
BuildRequires: gem(another_gem)

%description
%summary

%package -n %pkgname
Summary: summary
Group: Development/Other
BuildArch: noarch

%description -n %pkgname
%summary

%package doc
Summary: Documentation for <package>
Group: Development/Documentation
BuildArch: noarch

%description doc
Documentation for <package>.

%prep
%setup -q -n %pkgname-%version

%build
%gem_build

%install
%gem_show
%gem_install

%check
%gem_test

%files
%rubygem_gemdir/*
%rubygem_extdir/*
%rubygem_specdir/*

%files -n %pkgname
%_bindir/*

%files doc
%ruby_ridir/*

%changelog

Тестирование

Тестирование пакетов руби подсистемы проводится с помощью пакета gem-setup, который определяет и запускает необходимые для проверки руби пакета тесты, определенные в Gemspec/.gemspec. Для включения тестирования пакета необходимо включать в .spec пакета явные требования к зависимым пакетам на этапе сборки, напр.:

BuildRequires: gem(another_gem) >= 1.0 

Правила перехода на схему сию

1. Все зависимости Requires для всех подпакетов определяются автоматически, посему все такие зависимости должны быть отвержены;
2. Зависимости BuildRequires для пакета в случае, если проводится тестиование (раздел %check) или если это является крайне необходимым, должны быть прописаны явно, получены они могут быть с помощью приложения setup.rb;
3. Также в случае, если пакет был переименован, требуется явным образом прописать в Provides старое имя пакета;
4. В разделе %prep отвергаются все макросы указывающие на ruby, в частности %update_setup_rb;
5. В разделе %build все макросы указывающие на ruby, например %ruby_build, %ruby_config заменяются на %gem_build;
6. В разделе %install все макросы указывающие на ruby заменяются на %gem_install;
7. В разделе %check все макросы указывающие на ruby заменяются на %gem_test, хотя при крайней и неотложной необходимсти этот макрос может быть засерен;
8. В разделе %files для корневого пакета заменяются следующие макросы %[ruby]gem_specdir на %ruby_gemspecdir, %ruby_sitelibdir на %ruby_gemlibdir, %ruby_sitearchdir на %ruby_gemextdir;
9. В разделе %files для пакета документации %ruby_ri_sitedir макрос заменяется на %ruby_ridir.

Автоматизация

Для автоматизации надзора и обновления рубишных пакетов используется бисер gem-rubobot, который будет выполнять следующие функции:

• проводить надзор за новыми версиями пакетов и уведомлять об их появлении на rubygems.org;
• проводить надзор за новыми версиями руби и уведомлять об их появлении;
• осуществлять контроль целостности подсистемы бисеров с помощью специально созданного Gemfile;
• при достижении числа скачиваний бисера более определенного значения (по умолчанию 1 миллион), в автоматизированном пытаться опакечивать такой бисер, и уведомлять в случае как успеха, так и обратном случае;
• в автоматическом режиме пытаться обновить бисеры с учётом сохранения целостности бисерной подсистемы и уведомлять в случае невозможности обновить бисерный пакет;
• в автоматическом режиме пытаться обновить пакеты с приложениями на руби, который здесь также подразумевает попытку собирать приложение с заменой версии с помощью макроса, и уведомлять при невозможности собрать пакеты с приведенными правками;
• в полуавтоматическом режиме (то есть по прямой указивке оператора) собирать приложения руби с автоматическим созданием пакетов совместимости.
• в полуавтоматическом режиме (то есть по прямой указивке оператора) собирать руби с автоматическою пересборкою необходимых пакетов по зависимостям.