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. Строка для описания функции (help text).

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