Crazy Rebel: викификация, оформление, иллюстрация

Crazy Rebel — Sat, 28 Aug 2010 17:15:59 GMT

викификация, оформление, иллюстрация

Новая статья

: '''''Scilab''''' Создадим для него пакет расширений и обогатим новыми возможностями

==''Scilab'': Создаем Toolbox==

{{Цикл/SciLab}}

: Если возможностей, встроенных в ''Scilab'', недостаточно для ваших целей, '''Александр Бикмеев''' покажет, как обучить его новым трюкам (ко всеобщей пользе, разумеется).

Сегодня многие уже понимают, что свободное ПО часто может заменить проприетарное без особого ущерба для функциональности. Например, свободные математические пакеты прочно обосновались на жестких дисках не только зарубежных, но и российских пользователей. Но... оказывается, что для решения некоторых задач их возможностей не хватает. Что же делать? Наверное, следует действовать в лучших традициях мира Open Source – если чего-то недостает, то это следует создать самому! Тем более, что в программе Google Summer Code
все чаще появляются задачи по созданию расширений для свободных математических пакетов.

На данном уроке мы познакомимся со стандартной процедурой создания пакета расширений (Toolbox) для СКА ''Scilab'' ([[LXF106:SciLab|LXF106–109]]) при помощи макросов на встроенном языке программирования. Англоязычное руководство по написанию пакетов расширений можно найти на официальной вики: http://wiki.scilab.org/howto/Create_a_toolbox.

===Каталоги===

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

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

Кроме описанных подкаталогов, в корневом каталоге обычно располагаются 4 файла:
* '''readme.txt''' Описание самого пакета расширений, а также процесса его установки.
* '''builder.sce''' Основной скрипт сборки пакета...
* '''loader.sce'''...и основной скрипт его загрузки в ''Scilab''
* '''license.txt''' Лицензия.

Следует отметить, что данная структура не всегда реализуется полностью. Например, если в пакете нет функций, реализованных на ''C/C++'', можно обойтись без '''src'''; в отсутствие примеров не нужен каталог '''demos'''. В репозитории пакетов расширений на сайте ''Scilab'' встречаются экземпляры, состоящие из одного файла с функциями, без каких-либо скриптов сборки и установки. Но нам кажется, что соблюдение правил, определенных разработчиками – это верный путь к безошибочной работе конечного продукта.

В каталоге самого ''Scilab'' имеется шаблон нового пакета, который вы можете взять в качестве основы. Если вы используете двоичную версию ''Scilab'', загруженную вручную, то пакет-шаблон располагается в каталоге '''scilab/contrib/toolbox_skeleton'''; если же ''Scilab'' установлен при помощи менеджера пакетов, то ищите в каталогах '''/opt''' или '''/usr'''. Я пользуюсь Mandriva 2009.1, и у меня он находится в '''/usr/share/scilab/contrib/toolbox_skeleton'''.

===Добавим функции===

Давайте создадим пакет (назовем его '''Ballistic'''), в котором будут три функции, вычисляющие параметры движения тела, брошенного под углом к горизонту, в зависимости от времени:
* '''blst_height''' – высота тела,
* '''blst_length''' – дальность полета,
* '''blst_speed''' – вертикальная и горизонтальной скорости тела,

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

Напомним ([[LXF107:SciLab|LXF107]]), что код внешних функций в ''Scilab'' вводится в редакторе, а описание функции имеет вид:

function [<список выходных параметров>] =
<Имя Функции>(<список входных параметров>)
<тело функции>
endfunction

Создадим в домашнем каталоге новый, с именем '''Scilab_Toolbox''': здесь будут размещаться все пакеты расширений, загруженные из сети или созданные лично нами. Организуем в нем подкаталог для нашего пакета ('''ballistic'''). В соответствии с выбранным содержимым создадим подкаталоги '''macros''' и '''help'''.

{{Врезка|Содержание=[[Изображение:LXF122_81_1.jpg|300px]] Рис. 1. Текст первой функции будущего пакета расширений ''Ballistic''.|Ширина=300px}}

Запускаем ''Scilab'', открываем редактор либо командой ''scipad'', либо при помощи меню '''Инструменты > Редактор''' и вводим код, показанный на рис. 1. В самом тексте приведено достаточно комментариев, чтобы не вдаваться в его детальное объяснение. Поясним только один момент, который не совсем очевиден, а именно – для чего в тексте функции используется цикл.

Поскольку мы бросаем тело с поверхности Земли, которую полагаем плоской, то отрицательная высота не имеет смысла. В связи с этим в код добавлена проверка рассчитанного значения, и если оно оказывается отрицательным, мы принудительно устанавливаем его в ноль. Однако
проблема в том, что в качестве входных параметров функций ''Scilab'' может использоваться не одно значение, а массив. Если оставить
только один оператор сравнения, то оно будет выполнено только для первого элемента массива. В результате мы получим или массив нулевых
значений (если первый элемент будет отрицательным), или массив, в котором имеются и отрицательные, и положительные элементы.

Эта ошибка весьма типична для начинающих программировать в ''Scilab'', поскольку они часто забывают, что любая переменная в этой системе
рассматривается прежде всего как матрица. Таким образом, сравнение необходимо выполнить для всех элементов массива-результата, а для этого
необходим цикл.

Сохраним данный код в каталоге '''macros''' под именем '''blst_height.sci'''. Затем создадим файлы '''blst_length.sci''' и '''blst_speed.sci''', которые будут вычислять дальность полета тела и компоненты скорости соответственно. В качестве входных параметров
всех трех функций выступают '''g''' – ускорение свободного падения, '''v0''' – абсолютная величина начальной скорости, '''alpha''' – угол наклона к горизонту, '''t''' – время, прошедшее с момента начала движения. Эти функции длиннее, так что мы не будем приводить их текст в журнале: воспользуйтесь файлами с '''LXFDVD'''.

{{Врезка|Заголовок=Скорая помощь|Содержание=Не забывайте вставлять в код комментарии! Напомним, что строка-комментарий начинается с двойного слэша ('''//'''), и'' Scilab5'' вполне терпимо относится к кириллическому тексту.|Ширина=200px}}

Конечно же, тексты этих макросов можно набрать в простом текстовом редакторе типа ''Kate'', но использование ''Scipad'' позволяет проверить работу функции сразу после ввода. Для этого следует выбрать последовательно пункты меню '''Execute > Load into Scilab'''. После
этого в основном окне ''Scilab'' можно будет выполнить тестовые вычисления с функциями будущего пакета.

Загрузите функцию '''blst_height''' в ''Scilab'', как указано выше, и попробуйте следующие команды:

{{Врезка|Содержание=[[Изображение:LXF122_81_2.jpg|300px]] Рис. 2. Траектории движения тела после броска на Земле и на Луне. |Ширина=300px}}

-->t=0:0.1:3;
-->h1=blst_height(9.81,10,45,t);
-->h2=blst_height(1.62,10,45,t);
-->plot2d(t,[h1 h2],[color(0,255,0) color(255,128,0)]);
-->hl=legend([‘Земля’;’Луна’],2);

В результате получится график, показанный на рис. 2. На нем отображаются траектории первых трех секунд полета тела с одинаковыми исходными
параметрами, но на разных небесных телах: на Земле и на Луне (может, проверим, были ли там американцы?). Видно, что на Луне тело летит
выше, чем на Земле. Следовательно, функция работает. Мы рекомендуем вам разработать тестовые примеры для каждой функции, чтобы
впоследствии после любых изменений можно было убедиться, что новая версия функции дает тот же результат, что и старая. Собственно, для этого и нужны сценарии в подкаталоге '''unit tests''' нашего пакета.

{{Врезка|Звголовок=Именование макросов|Содержание=Текст каждой функции следует хранить в отдельном файле, название которого должно совпадать с именем самой функции. Дело в том, что после загрузки пакета расширений в рабочую среду система ищет в каждом файле
пакета функцию, имя которой совпадает с именем файла. То есть, если есть файл макроса с именем '''func1.sci''', то система будет искать в нем функцию с именем '''func1'''. Если в этом файле присутствует несколько функций, они станут доступны только после вызова функции '''func1'''. Если же в файле '''func1.sci''' функции '''func1''' не окажется, то все функции этого файла будут недоступны.

Размещение функций в отдельных файлах позволяет быстрее находить исходный текст необходимой функции, упрощает тестирование, а впоследствии
– и модернизацию пакета.|Ширина=400px}}

После того, как все макросы созданы, необходимо написать скрипт их сборки и загрузки. Это обычно делается вручную. В ''Scilab5'' появились специальные команды, упрощающие выполнение данной операции. Откройте каталог с макросами и создайте в нем простой текстовый документ с именем '''buildmacros.sce'''. Внутри него разместите следующий текст:

pathMB = get_absolute_file_path('buildmacros.sce');
tbx_build_macros('Ballistic', pathMB);
clear pathMB;

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

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

===Создаем описание===

Функции написаны, но если мы не сопроводим их поясняющим текстом, то вряд ли кто-то станет разбираться, как с ними работать. Одним из вариантов является использование комментариев; однако, чтобы просмотреть их, пользователю придется лезть в исходный код. Конечно же, есть люди, которые полезут в него в любом случае, но если пользователю необходимы пояснения, он обычно открывает справочное руководство.
Справочная система ''Scilab'' обладает замечательным свойством – она динамическая. То есть при загрузке в рабочую среду нового пакета расширений, его справочное руководство – если оно имеется – появляется в основном дереве руководства по всему пакету.

{{Врезка|Заголовок=Редактор справки|Содержание=На официальном сайте ''Scilab'' для создания текста справки рекомендуют использовать визуальный XML-редактор ''XMLmind'' (http://www.xmlmind.com/xmleditor/) вместе с шаблоном (http://www.scilab.org/download/xxe_scilab_config-1.1.0.tar.gz).

Скачиваем ''XMLmind'' и распаковываем в домашний каталог. Заходим в директорию программы, далее в подкаталог '''bin'', и запускаем скрипт ''xxe''.

Скачиваем шаблон и распаковываем его в каталог '''$HOME/.xxe4/addon''' (чтобы обнаружить каталог '''.xxe4''', необходимо включить режим отображения скрытых файлов).

Перезапускаем редактор, выбираем последовательно пункты меню '''File > New'''. После этого появляется список доступных шаблонов, среди которых присутствует раздел '''Scilab'''. Выбираем необходимый шаблон (для описания функции используется '''Refentry''') и нажимаем кнопку '''OK'''.

В появившемся пустом шаблоне заполняем все местозаполнители. Если необходимо вставить дополнительный абзац или элемент списка, нажимаем соответствующую кнопку на панели инструментов. В данном случае, для описания дополнительного параметра нам нужна '''Add listitem or varlistentry''' [Добавить элемент списка или элемент списка переменных].

По завершении, сохраняем файл в каталоге '''название_пакета/help/en_US''' и даем ему имя, совпадающее с названием описываемой функции. В качестве расширения оставляем '''.xml'''.|Ширина=400px}}

Для создания справочных материалов необходимо, чтобы в системе был установлен 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=”blst_height” 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>blst_height</refname>
<refpurpose> calculate height of body's trajectory, that was thrown from earth </refpurpose>
</refnamediv>

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

<refsynopsisdiv>
<title>Calling Sequence</title>
<synopsis>a = blst_height(g, v0, alpha, t)</synopsis>
</refsynopsisdiv>

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

<refsection>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term>g</term>
<listitem>
<para>gravitational acceleration</para>
</listitem>
</varlistentry>
...
</variablelist>
</refsection>

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

<refsection>
<title>Description</title>
<para>calculate height of body’s trajectory, that was thrown from earth from given gravitational acceleration,
initial speed and angle between the speed and horizon, and time since trow.</para>
</refsection>

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

<refsection>
<title>Examples</title>
<programlisting role=”example”>blst_height(9.81, 15,30, 3)</programlisting>
</refsection>

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

<refsection>
<title>Authors</title>
<simplelist type=”vert”>
<member>Alexander</member>
</simplelist>
</refsection>

После этого файл закрывается:

</refentry>

Создайте в каталоге '''help''' подкаталог '''en_US''' (к сожалению, ''Scilab'' поддерживает справку только на двух языках: английском и французском). Затем создайте в '''help/en_US''' три файла с описанием функций с расширением '''.xml'''.

Осталось создать там же сценарий сборки англоязычного справочного материала ('''build_help.sce''') со следующим содержанием:

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

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

Далее, перейдите на один уровень выше в каталог '''help'''. Здесь следует создать скрипт сборки всех справочных материалов '''builder_help.sce''':

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

{{Врезка|Содержание=[[Изображение:LXF122_83_1.jpg|300px]] Рис. 3. Справочная система ''Scilab'', содержащая главу по нашему пакету расширений ''Ballistic''.|Ширина=300px}}

===Управляющие скрипты===

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

mode(-1)
pathB = get_absolute_file_path('builder.sce');
tbx_builder_macros(pathB);
tbx_builder_help(pathB);
tbx_build_loader('Ballistic', pathB);
clear pathB;

В первой строке отключается вывод сообщений. В процессе разработки ее желательно закомментировать, иначе при возникновении ошибок вы можете о них не узнать. В следующих строках во временную переменную записывается путь к каталогу пакета расширений, затем происходит сборка макросов и справки и создание загрузчика для пакета. По завершении временная переменная уничтожается.
* '''etc/Ballistic.start''' Это основный скрипт загрузки пакета, вызываемый из загрузчика. В нем прописывается все, что необходимо сделать во время загрузки пакета расширений. Ниже приведено содержание такого скрипта для нашего пакета:

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

{{Врезка|Заголовок=Скорая помощь|Содержание=Желательно иметь два каталога с исходными текстами вашего пакета: один для хранения только исходных текстов, а второй – для сборки. В этом случае вам не придется чистить каталог от последствий сборки перед тем, как выпустить пакет в мир.|Ширина=200px}}

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

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

exec('~/Scilab_Toolbox/ballistic/builder.sce’);

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

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

Все, теперь можно использовать функции пакета в расчетах. Более того, можно открыть справку и в самом низу (иногда вверху) увидеть название нашего пакета – ''' 'Ballistic' '''. Щелкнув на этом пункте, можно посмотреть, правильно ли мы оформили справку (рис. 3). Если все сделано верно, то осталось только создать файлы с описанием установки и текстом лицензии.

Все скрипты, макросы и файлы справки можно создать, не запуская ''Scilab'': система понадобится только на последнем этапе для сборки пакета и проверки работоспособности. Более того, шаблоны скриптов можно взять из пакета ''toolbox_skeleton'' и убрать из них все лишнее или добавить свое.

Дерзайте! А если эта статья вас заинтересовала, то напишите нам ([mailto:letters@linuxformat.ru letters@linuxformat.ru]), что бы вы еще хотели узнать о создании пакетов расширений или программировании в ''Sсilab''. Разработка графического интерфейса, создание пакетов из имеющихся специализированных библиотек или собственного блока для ''Scicos'' – что вам интересно?
'''LXF'''

LXF122:SciLab - История изменений

Crazy Rebel: викификация, оформление, иллюстрация