• Пакетная компиляция (ocamlc)
• Интерактивная система, или REPL (ocaml)
• Система времени выполнения (ocamlrun)
• Компиляция в машинный код (ocamlopt)
• Генераторы лексических анализаторов и парсеров (ocamllex, ocamlyacc)
• Генератор зависимостей (ocamldep)
• Генератор документации (ocamldoc)
• Отладчик (ocamldebug)
• Отладка машинного кода (gdb, lldb)
• Профилирование (ocamlprof, perf)
• Взаимодействие C с OCaml
• Оптимизация с помощью Flambda
• Фаззинг с помощью afl-fuzz
• Трассировка времени выполнения с помощью событий среды выполнения
• Преобразование программы «Tail Modulo Constructor»
• Обнаружение гонок данных во время выполнения с помощью ThreadSanitizer

Глава 15. Система времени выполнения (ocamlrun)

Команда ocamlrun выполняет байт-кодовые файлы, созданные на этапе компоновки командой ocamlc.

1 Обзор

Команда ocamlrun состоит из трех основных частей: интерпретатора байт-кода, который непосредственно выполняет байт-кодовые файлы; распределителя памяти и сборщика мусора; а также набора функций C, реализующих примитивные операции, такие как ввод-вывод.

Команда ocamlrun используется следующим образом:

        ocamlrun options bytecode-executable arg1 ... argn

Первый аргумент, не являющийся параметром, считается именем файла с исполняемым байт-кодом. (Этот файл ищется как в путях поиска исполняемых файлов, так и в текущем каталоге.) Остальные аргументы передаются программе OCaml в массиве строк Sys.argv. Элемент 0 этого массива — имя исполняемого байт-кодового файла; элементы с 1 по n — оставшиеся аргументы arg₁ — arg_n.

Windows: В Windows среда выполнения OCaml раскрывает подстановочные символы * и ? в аргументах до выполнения любых других действий. Массив строк Sys.argv формируется с использованием раскрытых аргументов. Чтобы избежать такого поведения, можно написать пользовательскую точку входа на C, как описано в разделе 23.7.5.

Как упоминалось в главе 13, исполняемые байт-кодовые файлы, создаваемые командой ocamlc, являются самозапускающимися и автоматически запускают команду ocamlrun. То есть, если a.out — исполняемый байт-кодовый файл,

        a.out arg1 ... argn

работает точно так же, как

        ocamlrun a.out arg1 ... argn

Обратите внимание, что при непосредственном вызове a.out невозможно передать параметры команде ocamlrun.

Windows: В некоторых версиях Windows байт-кодовые файлы запускаются самостоятельно, только если их имя заканчивается на .exe. Рекомендуется всегда добавлять .exe к именам исполняемых байт-кодовых файлов, например компилировать с помощью ocamlc -o myprog.exe ..., а не ocamlc -o myprog ....

2 Параметры

Команда ocamlrun распознает следующие параметры командной строки.

-b

Если программа аварийно завершается из-за неперехваченного исключения, выводит подробную «трассировку стека» выполнения, показывающую, где было возбуждено исключение и какие вызовы функций оставались активными в этот момент. Трассировка стека выводится только в том случае, если исполняемый байт-кодовый файл содержит отладочную информацию, то есть был скомпилирован и скомпонован с установленным параметром -g команды ocamlc. Это равносильно установке флага b в переменной среды OCAMLRUNPARAM (см. ниже).

-config

Выводит номер версии ocamlrun и подробные сведения о конфигурации, затем завершает работу.

-I dir

Ищет динамически загружаемые библиотеки в каталоге dir в дополнение к стандартному пути поиска (см. раздел 15.3).

-m

Выводит магическое число указанного в аргументе исполняемого байт-кодового файла и завершает работу.

-M

Выводит магическое число, ожидаемое этой версией среды выполнения для исполняемых байт-кодовых файлов, и завершает работу.

-p

Выводит имена примитивов, известных этой версии ocamlrun, и завершает работу.

-t

Увеличивает уровень трассировки для отладочной среды выполнения (в противном случае игнорируется).

-v

Предписывает менеджеру памяти выводить сообщения о ходе работы в стандартный поток ошибок. Это равносильно установке v=61 в переменной среды OCAMLRUNPARAM (см. ниже).

-version

Выводит строку с версией и завершает работу.

-vnum

Выводит краткий номер версии и завершает работу.

Также учитываются следующие переменные среды:

CAML_LD_LIBRARY_PATH

Дополнительные каталоги для поиска динамически загружаемых библиотек (см. раздел 15.3).

OCAMLLIB

Каталог, содержащий стандартную библиотеку OCaml. (Если OCAMLLIB не задана, вместо нее будет использоваться CAMLLIB.) Используется для поиска файла конфигурации ld.conf, необходимого для динамической загрузки (см. раздел 15.3). Если переменная не задана, используется каталог библиотеки, указанный при компиляции OCaml.

OCAMLRUNPARAM

Задает параметры системы времени выполнения и сборки мусора. (Если OCAMLRUNPARAM не задана, вместо нее будет использоваться CAMLRUNPARAM.) Эта переменная должна содержать последовательность спецификаций параметров, разделенных запятыми. Для удобства запятые в начале переменной игнорируются, а несколько идущих подряд запятых считаются одной. Спецификация параметра состоит из буквы параметра, за которой следуют знак =, десятичное число (или шестнадцатеричное число с префиксом 0x) и необязательный множитель. Параметры описаны ниже; параметры l, m, M, n, o, s, v соответствуют полям записи control, описанной в модуле Gc.

b

(трассировка стека) Включает вывод трассировки стека, когда программа аварийно завершается из-за неперехваченного исключения. Можно указать необязательный аргумент: b=0 отключает вывод трассировки стека; b=1 равносильно параметру b и включает вывод трассировки стека; b=2 включает вывод трассировки стека и заставляет систему времени выполнения загружать отладочную информацию при запуске программы, а не при выводе трассировки. Параметр b=2 можно использовать, если среда выполнения не может загрузить отладочную информацию в момент вывода трассировки, например, если отсутствуют свободные файловые дескрипторы.

c

(cleanup_on_exit) Корректно завершает работу среды выполнения при выходе (см. caml_shutdown в разделе 23.7.6). Параметр также включает объединение выделений памяти в пулы (как при вызове caml_startup_pooled). Этот режим можно использовать для обнаружения утечек с помощью стороннего отладчика памяти.

d

(max_domains) Максимальное количество доменов, которые могут быть активны одновременно. По умолчанию — 128 на 64-разрядных платформах и 16 на 32-разрядных.

e

(runtime_events_log_wsize) Размер кольцевых буферов событий среды выполнения для каждого домена, заданный как степень двойки в словах. По умолчанию равен 16, что соответствует буферам объемом 64 тыс. слов, или 512 КБ, в 64-разрядных системах.

l

(stack_limit) Ограничение размера стека (в словах). Оно имеет значение и для среды выполнения байт-кода, и для среды выполнения машинного кода: OCaml всегда использует собственный стек, а не стек операционной системы.

m

(custom_minor_ratio) Ограничение объема недоступной памяти вне кучи, удерживаемой пользовательскими значениями в малой куче. Малая сборка мусора запускается, когда объем памяти, удерживаемой пользовательскими значениями в малой куче, достигает этого значения. Задается в процентах от размера малой кучи. По умолчанию: 100. Примечание: параметр применяется только к значениям, выделенным с помощью caml_alloc_custom_mem.

M

(custom_major_ratio) Целевое отношение объема недоступной памяти вне кучи, удерживаемой пользовательскими значениями (например, bigarray), расположенными в большой куче, к размеру большой кучи. Скорость сборки мусора настраивается таким образом, чтобы этот объем памяти занимали уже недоступные, но еще не собранные значения. Задается в процентах от размера большой кучи. По умолчанию: 44. Примечание: параметр применяется только к значениям, выделенным с помощью caml_alloc_custom_mem.

n

(custom_minor_max_size) Максимальный объем памяти вне кучи для каждого пользовательского значения, выделенного в малой куче. Если пользовательское значение, выделенное в малой куче, занимает больше этого количества байтов, только этот объем учитывается при расчете custom_minor_ratio, а остаток непосредственно учитывается при расчете custom_major_ratio. По умолчанию: 8192 байта. Примечание: параметр применяется только к значениям, выделенным с помощью caml_alloc_custom_mem.

o

(space_overhead) Основной параметр, задающий скорость большой сборки мусора. Подробности см. в документации модуля Gc.

p

(трассировка парсера) Включает поддержку отладки парсеров, сгенерированных с помощью ocamlyacc. При включенном параметре автомат с магазинной памятью, выполняющий парсеры, выводит трассировку своих действий. Этот параметр не принимает аргументов.

R

(рандомизация) По умолчанию включает рандомизацию всех хеш-таблиц (см. Hashtbl). Этот параметр не принимает аргументов.

s

(minor_heap_size) Размер малой кучи (в словах).

t

Задает уровень трассировки для отладочной среды выполнения (игнорируется стандартной средой выполнения).

v

(verbose) Определяет, какие сообщения сборщика мусора выводить в stderr. Значение представляет собой сумму выбранных значений из следующего списка:

1 (= 0x001)

Начало и окончание цикла большой сборки мусора.

2 (= 0x002)

Малая сборка мусора и этап большой сборки мусора.

4 (= 0x004)

Увеличение и уменьшение кучи.

8 (= 0x008)

Изменение размера стеков и таблиц менеджера памяти.

16 (= 0x010)

Уплотнение кучи.

32 (= 0x020)

Изменение параметров сборщика мусора.

64 (= 0x040)

Вычисление размера этапа большой сборки мусора.

128 (= 0x080)

Вызов функций финализации

256 (= 0x100)

Сообщения при запуске (загрузка исполняемого байт-кодового файла, разрешение ссылок на общие библиотеки).

512 (= 0x200)

Вычисление условия запуска уплотнения.

1024 (= 0x400)

Вывод статистики сборщика мусора при завершении программы.

2048 (= 0x800)

Отладочные сообщения сборщика мусора.

4096 (= 0x1000)

Изменения резервирования адресного пространства.

V

(verify_heap) выполняет проверку целостности кучи сразу после завершения цикла большой сборки мусора

W

Выводит предупреждения среды выполнения в stderr (например, если канал, открытый для файла, не закрыт перед завершением работы, если данные не сброшены и т. п.).

Множитель — это k, M или G, означающие умножение соответственно на 2¹⁰, 2²⁰ и 2³⁰. Если буква параметра не распознана, вся спецификация игнорируется; если отсутствует знак равенства или число, значение считается равным 1; если множитель не распознан, он игнорируется.

Например, на 32-разрядном компьютере в bash команда

        export OCAMLRUNPARAM='b,s=256k,v=0x015'

указывает последующему запуску ocamlrun выводить трассировки стека для неперехваченных исключений, установить начальный размер малой кучи в 1 мегабайт и выводить сообщение в начале каждого цикла большой сборки мусора, при изменении размера кучи и при запуске уплотнения.

CAMLRUNPARAM

Если переменная среды OCAMLRUNPARAM не найдена, вместо нее используется CAMLRUNPARAM. Если не найдена и CAMLRUNPARAM, используются значения по умолчанию.

PATH

Список каталогов, в которых выполняется поиск исполняемого байт-кодового файла.

3 Динамическая загрузка общих библиотек

На платформах, поддерживающих динамическую загрузку, ocamlrun может динамически связываться с общими библиотеками C (DLL), предоставляющими дополнительные примитивы C помимо тех, что доступны в стандартной системе времени выполнения. Имена этих библиотек указываются во время компоновки, как описано в разделе 23.1.4), и записываются в исполняемый байт-кодовый файл; затем ocamlrun находит эти библиотеки и разрешает ссылки на их примитивы при запуске исполняемой байт-кодовой программы.

Команда ocamlrun ищет общие библиотеки в следующих каталогах в указанном порядке:

1. Каталоги, указанные в командной строке ocamlrun с помощью параметра -I.
2. Каталоги, указанные в переменной среды CAML_LD_LIBRARY_PATH.
3. Каталоги, указанные во время компоновки с помощью параметра -dllpath команды ocamlc. (Эти каталоги записываются в исполняемый байт-кодовый файл.)
4. Каталоги, указанные в файле ld.conf. Этот файл находится в каталоге стандартной библиотеки OCaml и содержит имена каталогов (по одному в строке), в которых следует выполнять поиск. Обычно в нем содержится только одна строка с именем подкаталога stublibs каталога стандартной библиотеки OCaml. Пользователи могут добавить в этот файл имена других каталогов с часто используемыми общими библиотеками; однако для обеспечения единообразия установки мы рекомендуем устанавливать общие библиотеки непосредственно в системный каталог stublibs, а не добавлять строки в файл ld.conf. Команда ocamlrun добавляет строки из файлов ld.conf, найденных в каталогах, указанных в OCAMLLIB, CAMLLIB и каталоге стандартной библиотеки, именно в таком порядке.
5. Каталоги по умолчанию, в которых выполняет поиск системный динамический загрузчик. В Unix обычно это /lib и /usr/lib, а также каталоги, перечисленные в файле /etc/ld.so.conf и переменной среды LD_LIBRARY_PATH. В Windows сюда входят системные каталоги Windows, а также каталоги, перечисленные в переменной среды PATH.

4 Распространенные ошибки

В этом разделе описаны и объяснены наиболее часто встречающиеся сообщения об ошибках.

filename: no such file or directory

Если filename — имя самозапускающегося байт-кодового файла, это означает, что либо этот файл не существует, либо ему не удалось запустить интерпретатор байт-кода ocamlrun. Второй случай означает, что OCaml не был правильно установлен в вашей системе.

Cannot exec ocamlrun

(При запуске самозапускающегося байт-кодового файла.) Не удалось найти ocamlrun в пути поиска исполняемых файлов. Убедитесь, что OCaml правильно установлен в вашей системе.

Cannot find the bytecode file

Файл, который пытается выполнить ocamlrun (например, файл, указанный первым аргументом, не являющимся параметром), либо не существует, либо не является допустимым исполняемым байт-кодовым файлом.

Truncated bytecode file

Файл, который пытается выполнить ocamlrun, не является допустимым исполняемым байт-кодовым файлом. Вероятно, после создания он был усечен или поврежден. Удалите его и создайте заново.

Uncaught exception

Выполняемая программа содержит «неперехваченное» исключение. То есть в какой-то момент она возбуждает исключение, которое нигде не перехватывается. Это приводит к немедленному завершению программы. Выводится имя исключения, а также его строковые, байтовые и целочисленные аргументы (аргументы более сложных типов не выводятся корректно). Чтобы определить место возникновения неперехваченного исключения, скомпилируйте программу с параметром -g и запустите ее повторно под отладчиком ocamldebug (см. главу 20) либо запустите ее с помощью ocamlrun -b или задайте переменной среды OCAMLRUNPARAM значение b=1.

Out of memory

Выполняемой программе требуется больше памяти, чем доступно. Возможно, программа создает чрезмерно большие структуры данных или содержит слишком много вложенных вызовов функций, из-за чего переполняется стек. В некоторых случаях программа совершенно корректна, но ей просто требуется больше памяти, чем может предоставить ваш компьютер. В других случаях сообщение «нехватка памяти» указывает на ошибку в программе: бесконечную рекурсивную функцию, выделение чрезмерно большого массива, строки или байтовой последовательности, попытки построить бесконечный список или другую структуру данных и т. п.

Чтобы упростить диагностику этой ошибки, запустите программу с параметром -v команды ocamlrun или задайте переменной среды OCAMLRUNPARAM значение v=63. Если выводится много сообщений «Growing stack»…, вероятно, зациклилась рекурсивная функция. Если выводится много сообщений «Growing heap»… и размер кучи медленно увеличивается, вероятно, программа пытается построить структуру данных со слишком большим (возможно, бесконечным) числом ячеек. Если сообщений «Growing heap»… выводится мало, но размер кучи при этом резко увеличивается, вероятно, программа пытается создать чрезмерно большой массив, строку или байтовую последовательность.