A.1.1 Начало работы с Oct-файлами

Oct-файлы — это фрагменты кода C++, скомпилированные с помощью API Octave в динамически загружаемый объект. Они получили своё название от файла, содержащего объект, расширение которого — .oct.

Найти компилятор C++, использовать правильные параметры, добавить нужные пути к заголовочным файлам и т. д. — непростая задача. Octave автоматизирует этот процесс, предоставляя команду mkoctfile для сборки oct-файлов. Команда доступна из Octave или из командной строки оболочки.

: mkoctfile [-options] file …

: [output, status] = mkoctfile (…)

Функция mkoctfile компилирует исходный код, написанный на C, C++ или Fortran. В зависимости от параметров, использованных с mkoctfile, скомпилированный код можно вызывать из Octave или использовать как автономное приложение.

Команду mkoctfile можно вызвать из командной строки оболочки или из командной строки Octave. Вызов из командной строки Octave просто передаёт вызов командной строке оболочки. Любые выходные данные сохраняются в переменной output, а код завершения — в переменной status. Если команда вызвана без выходных аргументов и компиляция завершается неудачно, Octave выдаст ошибку. Однако, если программист запрашивает output или status, Octave лишь выдаст предупреждение, и программист сам должен проверить, успешно ли выполнена команда.

Команда mkoctfile принимает следующие параметры, все они необязательны, за исключением имени файла с кодом, который требуется скомпилировать:

‘-I DIR’

Добавить каталог включаемых файлов DIR в команды компиляции.

‘-D DEF’

Добавить определение DEF в вызов компилятора.

‘-l LIB’

Добавить библиотеку LIB в команду компоновки.

‘-L DIR’

Добавить каталог библиотек DIR в команду компоновки.

‘-M’

‘--depend’

Создать файлы зависимостей (.d) для исходных файлов C и C++.

‘-R DIR’

Добавить путь времени выполнения в команду компоновки.

‘-Wl,…’

Передать параметры компоновщику, например "-Wl,-rpath=…". Кавычки необходимы, поскольку запятые интерпретируются как разделители команд.

‘-W…’

Передать параметры ассемблеру, например "-Wa,OPTION".

‘-c’

Скомпилировать, но не выполнять компоновку.

‘-g’

Включить параметры отладки для компиляторов.

‘-o FILE’

‘--output FILE’

Имя выходного файла. Расширение по умолчанию — .oct (или .mex, если указан параметр ‘--mex’), если только не выполняется компоновка автономного исполняемого файла.

‘-p VAR’

‘--print VAR’

Вывести значение переменной конфигурации VAR. Переменные делятся на три категории:

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

ALL_CFLAGS                  INCLUDEDIR
   ALL_CXXFLAGS                LAPACK_LIBS
   ALL_FFLAGS                  LDFLAGS
   ALL_LDFLAGS                 LD_STATIC_FLAG
   BLAS_LIBS                   LFLAGS
   CC                          LIBDIR
   CFLAGS                      LIBOCTAVE
   CPICFLAG                    LIBOCTINTERP
   CPPFLAGS                    OCTAVE_LINK_OPTS
   CXX                         OCTINCLUDEDIR
   CXXFLAGS                    OCTAVE_LIBS
   CXXLD                       OCTAVE_LINK_DEPS
   CXXPICFLAG                  OCTLIBDIR
   DL_LDFLAGS                  OCT_LINK_DEPS
   F77                         OCT_LINK_OPTS
   F77_INTEGER8_FLAG           RDYNAMIC_FLAG
   FFLAGS                      SPECIAL_MATH_LIB
   FPICFLAG                    XTRA_CFLAGS
   INCFLAGS                    XTRA_CXXFLAGS

Переменные конфигурации Octave, как описано выше, но в настоящее время не используемые mkoctfile.

AR
   DEPEND_EXTRA_SED_PATTERN
   DEPEND_FLAGS
   FFTW3F_LDFLAGS
   FFTW3F_LIBS
   FFTW3_LDFLAGS
   FFTW3_LIBS
   FFTW_LIBS
   FLIBS
   LIBS
   RANLIB
   READLINE_LIBS

Переменные конфигурации Octave, предоставляемые только для справки. Пользователи не могут переопределять эти переменные, за исключением ‘OCTAVE_HOME’ и ‘OCTAVE_EXEC_HOME’.

Если в окружении заданы OCTAVE_HOME или OCTAVE_EXEC_HOME, значения других переменных корректируются соответствующим образом: вместо исходного значения каталога, указанного параметрами --prefix или --exec-prefix при настройке Octave, подставляются OCTAVE_HOME или OCTAVE_EXEC_HOME.

API_VERSION                 LOCALFCNFILEDIR
   ARCHLIBDIR                  LOCALOCTFILEDIR
   BINDIR                      LOCALSTARTUPFILEDIR
   CANONICAL_HOST_TYPE         LOCALVERARCHLIBDIR
   DATADIR                     LOCALVERFCNFILEDIR
   DATAROOTDIR                 LOCALVEROCTFILEDIR
   DEFAULT_PAGER               MAN1DIR
   EXEC_PREFIX                 MAN1EXT
   EXEEXT                      MANDIR
   FCNFILEDIR                  OCTAVE_EXEC_HOME
   IMAGEDIR                    OCTAVE_HOME
   INFODIR                     OCTAVE_VERSION
   INFOFILE                    OCTDATADIR
   LIBEXECDIR                  OCTDOCDIR
   LOCALAPIARCHLIBDIR          OCTFILEDIR
   LOCALAPIFCNFILEDIR          OCTFONTSDIR
   LOCALAPIOCTFILEDIR          STARTUPFILEDIR
   LOCALARCHLIBDIR

‘--link-stand-alone’

Выполнить компоновку автономного исполняемого файла.

‘--mex’

Предположить, что создаётся файл MEX. Установить расширение выходного файла по умолчанию .mex.

‘-s’

‘--strip’

Удалить отладочную информацию из выходного файла.

‘-v’

‘--verbose’

Выводить команды по мере их выполнения.

‘file’

Файл для компиляции или компоновки. Распознаются следующие типы файлов:

.c    C source
   .cc   C++ source
   .cp   C++ source
   .cpp  C++ source
   .CPP  C++ source
   .cxx  C++ source
   .c++  C++ source
   .C    C++ source
   .f    Fortran source (fixed form)
   .F    Fortran source (fixed form)
   .f90  Fortran source (free form)
   .F90  Fortran source (free form)
   .o    object file
   .a    library file

Рассмотрим следующий небольшой пример, который знакомит с основами написания функции на C++, компонуемой с Octave.

#include <octave/oct.h>

DEFUN_DLD (helloworld, args, nargout,
           "Hello World Help String")
{
  octave_stdout << "Hello World has "
                << args.length () << " input arguments and "
                << nargout << " output arguments.\n";

  // Return empty matrices for any outputs
  octave_value_list retval (nargout);
  for (int i = 0; i < nargout; i++)
    retval(i) = octave_value (Matrix ());

  return retval;
}

Первая важная строка — #include <octave/oct.h>, которая предоставляет большинство определений, необходимых для oct-файла C++. Обратите внимание, что octave/oct.h — это заголовочный файл C++, который нельзя напрямую подключить с помощью #include в исходном файле C или на любом другом языке.

Файл oct.h содержит определение макроса DEFUN_DLD, создающего динамически загружаемую функцию. Этот макрос принимает четыре аргумента:

1. Имя функции, под которым она будет доступна в Octave,
2. Список аргументов функции типа octave_value_list,
3. Число выходных аргументов, которое можно — и часто следует — опустить, если оно не используется, и
4. Строку справочного текста функции.

Тип возвращаемого значения функций, определённых с помощью DEFUN_DLD, всегда — octave_value_list.

При выборе имени функции важно учитывать несколько моментов. Во-первых, оно должно быть допустимым именем функции Octave, то есть состоять из букв, цифр и символов подчёркивания и не начинаться с цифры. Во-вторых, поскольку Octave использует имя функции, чтобы определить имя файла, в котором следует искать функцию, имя функции в макросе DEFUN_DLD должно совпадать с именем файла oct-файла. Поэтому приведённая выше функция должна находиться в файле helloworld.cc, а скомпилировать её в oct-файл можно следующей командой:

mkoctfile helloworld.cc

В результате будет создан файл helloworld.oct — скомпилированная версия функции. Следует отметить, что в одном исходном файле вполне допустимо иметь несколько функций DEFUN_DLD. Однако для каждой из функций, определённых в исходном коде с помощью макроса DEFUN_DLD, необходимо либо создать символическую ссылку на oct-файл, либо использовать функцию autoload (Файлы функций).

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

helloworld (1, 2, 3)
-| Hello World has 3 input arguments and 0 output arguments.

В следующих разделах рассматривается использование отдельных классов из внутренних компонентов ядра Octave. Базовые классы, такие как dMatrix (матрица значений типа double), находятся в каталоге liboctave/array. Основным источником сведений об использовании конкретного класса служит сам файл заголовка. Однако часто для работы с классом достаточно изучить примеры в руководстве.