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.

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                  LAPACK_LIBS
   ALL_CXXFLAGS                LDFLAGS
   ALL_FFLAGS                  LD_CXX
   ALL_LDFLAGS                 LD_STATIC_FLAG
   BLAS_LIBS                   LFLAGS
   CC                          LIBDIR
   CFLAGS                      LIBOCTAVE
   CPICFLAG                    LIBOCTINTERP
   CPPFLAGS                    OCTAVE_LINK_OPTS
   CXX                         OCTINCLUDEDIR
   CXXFLAGS                    OCTAVE_LIBS
   CXXPICFLAG                  OCTAVE_LINK_DEPS
   DL_LD                       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
   INCLUDEDIR

Переменные конфигурации 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. Окончательное руководство по использованию конкретного класса содержится в самом заголовочном файле. Однако часто достаточно просто изучить примеры в руководстве, чтобы научиться использовать класс.