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