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

Oct-файлы представляют собой фрагменты кода C++, скомпилированные с помощью Octave API в динамически загружаемый объект. Они получили своё название от файла, содержащего объект, имеющего расширение .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 установлены в среде, то другие переменные корректируются соответственно с заменой OCTAVE_HOME или OCTAVE_EXEC_HOME вместо исходного значения каталога, указанного опциями --prefix или --exec-prefix, которые использовались при конфигурировании Octave.

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>, которая делает доступными большинство необходимых определений для C++ oct-файла. Обратите внимание, что 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. Однако должна быть символическая ссылка на oct-файл для каждой из функций, определённых в исходном коде с помощью макрокоманды DEFUN_DLD, или должна использоваться функция autoload (Функции файлов).

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

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

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