Содержание


SCILAB

Часть 2. Создание пакета расширений на встроенном языке Scilab

Серия контента:

Этот контент является частью # из серии # статей: SCILAB

Следите за выходом новых статей этой серии.

Этот контент является частью серии:SCILAB

Следите за выходом новых статей этой серии.

Что такое Toolbox (пакет расширений)

Scilab (EN) – с одной стороны, это математический пакет численных расчетов, а с другой – платформа для разработки высокотехнологичных приложений. У нее есть все атрибуты среды разработки: текстовый редактор, компилятор и интерпретатор, язык программирования, средства отладки.

Таким образом, платформа предоставляет возможности разработки. Если посмотреть в прилагаемом справочном руководстве, то сама система Scilab содержит сравнительно небольшой набор служебных слов и констант. Львиная доля функционала математического пакета реализуется дополнительными функциями, собранными в тематические пакеты – Toolbox. Поскольку эти пакеты расширяют функциональность базовой системы, то их также принято называть «пакетами расширений».

Варианты построения пакета расширений

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

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

В данной статье мы рассмотрим создание пакета, содержащего функции на встроенном языке программирования Scilab, а в следующей – изучим, как создавать пакеты расширений на базе уже существующих библиотек или функций, написанных на таких языках, как C или Fortran.

Структура каталогов

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

  • macros: здесь расположены макросы на встроенном языке Scilab, т.е. файлы-функции с расширением .sci, а также скрипт сборки buildmacros.sce.
  • src: если функции пакета написаны на стороннем языке программирования, таком как C или Fortran, то в этом каталоге должны находиться файлы с их исходным кодом подпрограмм-функций (с расширениями .c и .f) и сценарий их сборки buildsrc.sce.
  • sci_gateway: в этом каталоге следует размещать подпрограммы-интерфейсы для функций, написанных на сторонних языках программирования (C, Fortran).
  • help: в этом каталоге находится текст справки, представляющий собой набор XML-файлов, созданных в соответствии с определенным шаблоном. Справочные материалы могут быть представлены на английском и французском языках, в подкаталогах с соответствующими именами eng и fr. Кроме того, в этом каталоге должен размещаться традиционный скрипт сборки справочного материала: builder_help.sce.
  • etc: если пакет использует в своей работе еще какие-либо файлы (.html, .pdf, .txt, .jpeg, …), то они размещаются здесь. Кроме того, тут располагаются скрипты подготовки загрузки и выгрузки пакета из системы.
  • tests: этот каталог содержит скрипты с расширением .tst, необходимые для тестирования работоспособности и корректности работы пакета расширений.
  • demos: в этом каталоге размещаются примеры, иллюстрирующие работу пакета.
  • includes: здесь располагаются заголовочные файлы (с расширением .h) для исходных текстов C.

Кроме того, в базовом каталоге пакета обычно располагаются четыре файла:

  • readme.txt: описание пакета расширений, а также, что является стандартным для UNIX-систем, – процесса его установки.
  • builder.sce: основной скрипт сборки всего пакета. Обычно он последовательно вызывает все остальные скрипты, расположенные в соответствующих подкаталогах.
  • loader.sce: основный скрипт загрузки пакета расширений в Scilab.
  • license.txt: файл с текстом лицензии, по которой распространяется пакет.

Приведенная структура является базовой, а потому включает все каталоги, которые могут содержаться в пакете, однако это не означает, что они обязаны присутствовать. Например, если для пакета не созданы тестовые примеры, то можно не создавать каталог tests, а если для пакета не разработаны примеры использования, то можно обойтись и без каталога demos.

Если вы не используете какие-то части стандартной структуры, то это, конечно же, не означает, что их не должно быть. Один из вариантов – это создать шаблон пакета расширений, чтобы в начале разработки скопировать его в новый каталог и начать заполнение необходимых каталогов, а неиспользуемые каталоги оставить пустыми. Именно это и сделали разработчики Scilab. В последние версии пакета встраивается каталог tollbox_skeleton, который можно найти в каталоге contrib. Если же вы используете версию, установленную посредством менеджера пакетов, то, например, в Mandriva путь к нему выглядит так: /usr/share/scilab/contrib/.

Замечания к разработке скриптов для пакета расширений

При разработке скриптов, т.е. файлов с функциями на встроенном языке программирования Sсilab, следует соблюдать следующие правила.

  1. В каждом файле должна быть только одна функция, которая вызывается извне. Иными словами, в файле могут присутствовать и другие функции, но желательно, чтобы там находились только те, которые используются внутри основной.
  2. Имя файла должно совпадать с названием основной функции файла.

Дело в том, что при обращении к файлу Sсilab ищет в нем одноименную функцию. Если таковой не обнаруживается, то файл пропускается. Кроме того, размещение каждой функции в отдельном файле позволяет локализовать ошибки и ускорить модификацию пакета.

Мы воспользуемся файлом функции, созданном в предыдущей статье (edIzm.sci) и создадим пакет с этой единственной функцией и названием MyToolbox.

Скрипт сборки функций

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

Скрипт сборки функций, написанных на встроенном языке, располагается в каталоге macros и, согласно внутренним соглашениям, носит имя buildmacros.sce. Он пишется автором пакета самостоятельно. В Scilab5 появились специальные команды, упрощающие выполнение данной операции. При использовании Scilab в Linux, эти функции устанавливаются вместе с платформой, в случае же ОС Windows, во время установки необходимо дополнительно выбрать пункты: Parameters Toolbox, Development Tools и A toolbox skeleton – или просто выбрать полную установку.

Итак, в каталоге macros создадим простой текстовый документ с именем buildmacros.sce. В нем разместим следующий текст:

pathMB = get_absolute_file_path('buildmacros.sce');
printf('Building macros in %s\n', pathMB);
tbx_build_macros("MyToolbox", pathMB);
clear pathMB;

и сохраним файл. Рассмотрим этот скрипт построчно.

  • Первая строка: во временную переменную pathMB заносится абсолютный путь к каталогу, где расположены разработанные макросы-функции. Этот путь необходим компилятору.
  • Вторая строка: приведена команда вывода сообщения пользователю о том, что сборка выполняется. Конечно же, это не обязательно, но является проявлением уважения к пользователю.
  • Третья строка: команда, выполняющую сборку всех макросов, расположенных в данном каталоге. В качестве параметров указываются название пакета, а также путь к каталогу с макросами.
  • Четвертая строка: из памяти удаляется временная переменная.

В результате выполнения данного скрипта в каталоге macros создаются:

  • бинарные версии макросов (файлы с расширением .bin);
  • текстовый файл names с перечнем имен собранных функций пакета;
  • бинарный файл lib, представляющий собой системную переменную с перечнем всех функций пакета.

Таким образом, если вы не хотите распространять исходные тексты вашего пакета, то скопируйте каталог пакета в новое место и оставьте в каталоге macros только перечисленные выше файлы. Все остальное в этом каталоге можно будет удалить.

Создание справочных материалов

«Ахиллесова пята» свободного программного обеспечения – это отсутствие документации. Если разработанный пакет будет распространяться с исходными текстами функций, то можно разместить в теле функций комментарии, однако немногие станут открывать код функций, чтобы разобраться с тем, как они работают. Более вероятно, что после нескольких неудачных попыток разобраться с пакетом методом проб и ошибок пользователь отбросит пакет и поищет что-то более понятное. Именно поэтому разработка документации чрезвычайно важна для успешного продвижения пакета расширений.

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

Справочные материалы представляют собой XML-файлы, обычно по одному для каждой функции. Для их создания необходимо, чтобы в системе был установлен XML-анализатор sabcmd, являющийся частью пакета Sablotron, который можно найти в менеджере пакетов вашего дистрибутива. Если же там его не оказалось, то скачайте Sablotron здесь: http://www.gingerall.org/downloads.html.

Структура XML-файла справки достаточно проста, и его можно создать в любом текстовом редакторе. В первой строке файла указывается версия XML, а также используемая кодировка текста:

<?xml version="1.0" encoding="UTF-8"?>

Затем идет «шапка» для Scilab, в которой указывается версия Scilab, название функции, язык справочного материала, а также определяются некоторые пространства имен.

<refentry version="5.0-subset Scilab" xml:id="edIzm" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:ns3="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook">

Далее идет краткое описание самой функции:

  <refnamediv>
    <refname>edIzm</refname>
    <refpurpose> returns name of measurement units of this value 
	of Information's size </refpurpose>
  </refnamediv>

Затем указывается стандарт вызова:

  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>a = edIzm(N)</synopsis>
  </refsynopsisdiv>

Следующая секция описывает параметры, передаваемые нашей функции:

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term>N</term>
        <listitem>
          <para>Value of Information's size</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

В нашем примере параметр лишь один, но если у вашей функции параметров больше, то каждый из них можно описать в своем блоке varlistentry.

Далее идет раздел описания: в нем сообщается, что это за функция, для чего она нужна и так далее. Каждый параграф заключается в тег para.

  <refsection>
    <title>Description</title>
    <para> It takes value of Information's size, calculate number of
	digits, and on this basis returns name of measurement units</para>
  </refsection>

Следующий раздел предлагает примеры использования данной функции.

  <refsection>
    <title>Examples</title>
    <programlisting role="example">edIzm(1200000)</programlisting>
  </refsection>

В конце могут быть указаны необязательные разделы, такие как «Автор» и «Смотри также».

  <refsection>
    <title>Authors</title>
    <simplelist type="vert">
      <member>Alexander</member>
    </simplelist>
  </refsection>
После этого файл закрывается.
</refentry>

Редактор справочных материалов

Как вы могли видеть в предыдущем пункте, файлы справки можно создавать в любом текстовом редакторе, достаточно знать XML-теги. Однако для большего комфорта на официальном сайте Scilab рекомендуют использовать визуальный XML-редактор XMLmind вместе с шаблоном.

Рассмотрим процедуру создания файла-описания нашей функции edIzm в этом редакторе.

  1. Скачиваем XMLmind и распаковываем в домашний каталог. Заходим в каталог распакованного приложения, затем в подкаталог bin и запускаем скрипт xxe.
  2. Скачиваем шаблон и распаковываем его в каталог /home/username/.xxe4/addon (чтобы обнаружить каталог .xxe4, необходимо включить режим отображения скрытых файлов).
  3. Перезапускаем редактор, выбираем последовательно пункты меню File > New. После этого появляется список доступных шаблонов, среди которых присутствует раздел Scilab. Выбираем необходимый шаблон (для описания функции используется Refentry) и нажимаем кнопку Ok (рисунок 1).
    Рисунок 1. Выбор шаблона
    Рисунок 1. Выбор шаблона
    Рисунок 1. Выбор шаблона
  4. В появившемся пустом шаблоне заполняем все местозаполнители. Если необходимо вставить дополнительный абзац или элемент списка, нажимаем соответствующую кнопку на панели инструментов (рисунок 2).
    Рисунок 2. Заполнение шаблона описания функции содержимым
    Рисунок 2. Заполнение шаблона описания функции содержимым
    Рисунок 2. Заполнение шаблона описания функции содержимым
  5. По завершении сохраняем файл в соответствующем каталоге справочных материалов, в нашем случае это будет MyToolbox/help/en_US, и даем ему имя, совпадающее с названием описываемой функции, т.е. edIzm. В качестве расширения оставляем .xml.

Сборка справки

Файлы справки должны размещаться в подкаталогах каталога help. К сожалению, Scilab поддерживает справку только на двух языках: английском и французском, поэтому вы можете создать каталог en_US для англоязычного варианта. Далее в этот каталог следует поместить созданный XML-файл с описанием функций. В нашем пакете только одна функция, поэтому мы создаем в каталоге файл edIzm.xml.

Практически в каждом каталоге пакета расширений необходим свой скрипт сборки, поэтому для справки таких скриптов два: первый располагается в каталоге help (он выполняет сборку всего справочного материала), а второй, располагающийся в каталоге с файлами на определенном языке, управляет сборкой локализованной копии справки. Итак, создадим в каталоге en_US скрипт с именем build_help.sce, содержащий следующее:

pathHB = get_absolute_file_path('build_help.sce');
tbx_build_help('MyToolbox', pathHB);
clear pathHB;

Справка на английском языке создана, осталось создать скрипт сборки всего справочного материала. Для этого перейдите на один уровень выше в каталог help, создайте текстовый файл с именем builder_help.sce, содержащий следующие строки:

pathH = get_absolute_file_path('builder_help.sce');
tbx_builder_help_lang("en_US", pathH);
clear pathH;

Общие скрипты сборки и загрузки пакета

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

builder.sce Это главный сценарий сборки пакета. Он располагается в базовом каталоге и в нашем случае содержит следующие строки:

// отключаем вывод служебных сообщений
mode(-1) 
//Запоминаем путь к каталогу пакета
pathB = get_absolute_file_path('builder.sce');
// Сборка макросов
tbx_builder_macros(pathB);
// Сборка справки
tbx_builder_help(pathB);
// формирование загрузчика пакета
tbx_build_loader('MyToolbox', pathB);
clear pathB;

etc/MyToolbox.start Это основный скрипт, содержащий все действия, которые необходимо выполнить при загрузке пакета, вызывается он из главного загрузчика. Вот примерное содержимое этого скрипта:

//Запоминаем режим вывода предупреждений
warning_mode = warning('query');
//Отключаем режим вывода предупреждений
warning('off');
//получаем путь к корневому каталогу пакета
etc_tlbx = get_absolute_file_path('MyToolbox.start');
etc_tlbx = getshortpathname(etc_tlbx);
root_tlbx = strncpy( etc_tlbx, length(etc_tlbx)-length('\etc\') );
//получаем путь к каталогу с макросами
pathmacros = pathconvert( root_tlbx ) + 'macros'+ filesep();
//Загружаем функции пакета
MyToolboxlib = lib(pathmacros);
//Восстанавливаем режим вывода предупреждений
warning(warning_mode);
//Добавляем новую главу в справочное руководство Scilab
path_addchapter = root_tlbx + "/jar/";
if ( fileinfo(path_addchapter) <> [] ) then
  add_help_chapter('MyToolbox', path_addchapter, %F);
  clear add_help_chapter;
end
//удаляем все временные переменные
clear warning_mode;
clear path_addchapter;
clear root_tlbx;
clear etc_tlbx;
clear pathmacros;
clear pathconvert;

etc/Ballistic.quit Сценарий, определяющий, что следует выполнить при выгрузке пакета. Обычно его оставляют пустым.

Итак, все готово! Запускаем Scilab и вводим команду на сборку нашего пакета, т.е. вызываем основной сборочный сценарий:

exec('~/Scilab_Toolbox/MyToolbox/builder.sce');

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

exec('~/Scilab_Toolbox/MyToolbox/loader.sce');

После успешного выполнения команд функцию нашего пакета можно вызвать из основной оболочки, а также открыть справку и посмотреть описание нашей функции (рисунки 3 и 4). Если все сделано верно, то осталось только создать файлы с описанием установки и текстом лицензии.

Рисунок 3. Консоль Scilab после загрузки пакета и вызова функции
Рисунок 3. Консоль Scilab после загрузки пакета и вызова функции
Рисунок 3. Консоль Scilab после загрузки пакета и вызова функции
Рисунок 4. Система справки с загруженным руководством по пакету
Рисунок 4. Система справки с загруженным руководством по пакету
Рисунок 4. Система справки с загруженным руководством по пакету

Заключение

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

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


Ресурсы для скачивания


Похожие темы

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=Linux
ArticleID=494966
ArticleTitle=SCILAB: Часть 2. Создание пакета расширений на встроенном языке Scilab
publish-date=06082010