Руководство пользователя компилятора Nim

"Посмотри на себя, хакер. Жалкая тварь из плоти и крови, задыхающаяся и потеющая, пока бежишь по моим коридорам. Как ты можешь бросить вызов совершенной, бессмертной машине?"

Введение

Этот документ описывает использование компилятора Nim на различных поддерживаемых платформах. Это не определение языка программирования Nim (которое описано в руководстве).

Nim — это свободное программное обеспечение; оно лицензировано по лицензии MIT.

Использование компилятора

Переключатели командной строки

Все параметры, принимающие аргумент PATH или DIR, подвержены подстановке путей:

• $nim: Глобальный путь префикса nim
• $lib: Путь stdlib
• $home и ~: Путь домашней директории пользователя
• $config: Директория модуля, который компилируется в данный момент
• $projectname: Имя файла проекта без расширения
• $projectpath и $projectdir: Путь к файлу проекта
• $nimcache: Путь nimcache

Основные переключатели командной строки:

Использование:

nim command [options] [projectfile] [arguments]

Команда:

Аргументы: аргументы передаются выполняемой программе (если выбран параметр --run)

Параметры:

Обратите внимание, что однобуквенные параметры, принимающие аргумент, требуют двоеточия. Например, -p:PATH.

Расширенные переключатели командной строки:

Проверки во время выполнения (см. -x):

Расширенные параметры:

Список предупреждений

Каждое предупреждение может быть активировано индивидуально с помощью --warning:NAME:on|off или в директиве push с {.warning[NAME]:on|off.}.

Список подсказок

Каждая подсказка может быть активирована индивидуально с помощью --hint:NAME:on|off или в директиве push с {.hint[NAME]:on|off.}.

Уровни подробности

Символы времени компиляции

С помощью переключателя -d:x или --define:x вы можете определить символы времени компиляции для условной компиляции. Определённые переключатели могут быть проверены в исходном коде с помощью оператора when и процедуры defined. Типичное использование этого переключателя — включение сборки в режиме релиз (-d:release), где включены оптимизации для лучшей производительности. Ещё одним распространённым использованием является переключатель -d:ssl для активации сокетов SSL.

Кроме того, вы можете передать значение вместе со символом: -d:x=y, что может быть использовано в сочетании с директивами определения времени компиляции для переопределения символов во время сборки.

Символы времени компиляции полностью нечувствительны к регистру и знаки подчёркивания также игнорируются. --define:FOO и --define:foo идентичны.

Символы времени компиляции, начинающиеся с префикса nim, зарезервированы для реализации и не должны использоваться в других местах.

Файлы конфигурации

Примечание: Имя файла проекта — это имя файла .nim, передаваемого в качестве аргумента командной строки компилятору.

Исполняемый файл nim обрабатывает файлы конфигурации в следующих каталогах (в этом порядке; более поздние файлы перезаписывают предыдущие настройки):

1. $nim/config/nim.cfg, /etc/nim/nim.cfg (UNIX) или <Nim's installation directory>\config\nim.cfg (Windows). Этот файл можно пропустить с помощью параметра командной строки --skipCfg.
2. Если переменная среды XDG_CONFIG_HOME определена, $XDG_CONFIG_HOME/nim/nim.cfg или ~/.config/nim/nim.cfg (POSIX) или %APPDATA%/nim/nim.cfg (Windows). Этот файл можно пропустить с помощью параметра командной строки --skipUserCfg.
3. $parentDir/nim.cfg где $parentDir обозначает любой родительский каталог пути к файлу проекта. Эти файлы можно пропустить с помощью параметра командной строки --skipParentCfg.
4. $projectDir/nim.cfg где $projectDir обозначает путь к файлу проекта. Этот файл можно пропустить с помощью параметра командной строки --skipProjCfg.
5. Проект также может иметь файл конфигурации, специфичный для проекта, с именем $project.nim.cfg, расположенный в той же директории, что и $project.nim. Этот файл можно пропустить с помощью параметра командной строки --skipProjCfg.

Параметры командной строки имеют приоритет над настройками файлов конфигурации.

По умолчанию сборка проекта — это сборка отладки. Чтобы скомпилировать сборку релиза, определите символ release.

nim c -d:release myproject.nim

Чтобы скомпилировать опасную сборку релиза, определите символ danger.

nim c -d:danger myproject.nim

Обработка пути поиска

Nim имеет понятие глобального пути поиска (PATH), который используется для определения местоположения импортированных модулей или файлов включения. Если найдено несколько файлов, возникает ошибка неоднозначности.

nim dump показывает содержимое PATH.

Однако перед использованием PATH проверяется текущий каталог на предмет существования файла. Таким образом, если PATH содержит $lib и $lib/bar, и структура каталогов выглядит следующим образом:

$lib/x.nim
$lib/bar/x.nim
foo/x.nim
foo/main.nim
other.nim

И main импортирует x, то импортируется foo/x. Если other импортирует x, то $lib/x.nim и $lib/bar/x.nim соответствуют, но используется $lib/x.nim, поскольку это первое совпадение.

Каталог сгенерированного кода C

Все сгенерированные Nim файлы помещаются в подкаталог nimcache. Полный путь:

• $XDG_CACHE_HOME/nim/$projectname(_r|_d) или ~/.cache/nim/$projectname(_r|_d) на Posix
• $HOME\nimcache\$projectname(_r|_d) на Windows.

Суффикс _r используется для сборок релиза, _d — для сборок отладки.

Это упрощает удаление всех сгенерированных файлов.

Параметр --nimcache переключатель компилятора может использоваться для изменения каталога nimcache.

Однако сгенерированный C-код не является независимым от платформы. C-код, сгенерированный для Linux, не компилируется на Windows, например. В комментарии вверху файла C перечислены операционная система, процессор и CC, для которых был скомпилирован файл.

Выбор компилятора

Чтобы изменить компилятор с компилятора по умолчанию (в командной строке):

nim c --cc:llvm_gcc --compile_only myfile.nim

Это использует конфигурацию, определенную в config\nim.cfg для llvm_gcc.

Если nimcache уже содержит скомпилированный код другого компилятора для того же проекта, добавьте флаг -f для принудительной перекомпиляции всех файлов.

Компилятор по умолчанию определяется в верхней части config\nim.cfg. Изменение этой настройки влияет на компилятор, используемый koch для (пере)сборки Nim.

Для использования переменной среды CC используйте nim c --cc:env myfile.nim. Для использования переменной среды CXX используйте nim cpp --cc:env myfile.nim. --cc:env доступен начиная с версии Nim 1.4.

Кросс-компиляция

Для кросс-компиляции, например:

nim c --cpu:i386 --os:linux --compileOnly --genScript myproject.nim

Затем переместите C-код и скрипт компиляции compile_myproject.sh на вашу машину Linux i386 и запустите скрипт.

Другой способ — заставить Nim вызывать кросс-компиляторную цепочку инструментов:

nim c --cpu:arm --os:linux myproject.nim

Для кросс-компиляции компилятор вызывает C-компилятор с именем, подобным $cpu.$os.$cc (например, arm.linux.gcc) с опциями, определенными в $cpu.$os.$cc.options.always. Система конфигурации используется для предоставления осмысленных значений по умолчанию. Например, для Linux на 32-битном процессоре ARM ваш файл конфигурации должен содержать что-то вроде:

arm.linux.gcc.path = "/usr/bin"
arm.linux.gcc.exe = "arm-linux-gcc"
arm.linux.gcc.linkerexe = "arm-linux-gcc"
arm.linux.gcc.options.always = "-w -fmax-errors=3"

Кросс-компиляция для Windows

Для кросс-компиляции для Windows из Linux или macOS с помощью цепочки инструментов MinGW-w64:

nim c -d:mingw myproject.nim
# `nim r` also works, running the binary via `wine` or `wine64`:
nim r -d:mingw --eval:'import os; echo "a" / "b"'

Используйте --cpu:i386 или --cpu:amd64 для переключения архитектуры процессора.

Цепочка инструментов MinGW-w64 может быть установлена следующим образом:

apt install mingw-w64   # Ubuntu
yum install mingw32-gcc
yum install mingw64-gcc # CentOS - requires EPEL
brew install mingw-w64  # OSX

Кросс-компиляция для Android

Есть два способа компиляции для Android: программы терминала (Termux) и с помощью NDK (Android Native Development Kit).

Первый способ — рассматривать Android как обычный Linux и использовать Termux для подключения и непосредственного запуска компилятора Nim на Android, как если бы это был Linux. Эти программы — только консольные и не могут быть распространяться в Play Store.

Используйте обычные nim c внутри Termux, чтобы создать программы терминала для Android.

Обычные приложения Android написаны на Java. Чтобы использовать Nim внутри приложения Android, вам нужен небольшой Java-заглушка, который вызывает нативный библиотеку, написанную на Nim, используя NDK. Вы также можете использовать native-activity, чтобы заглушка Java генерировалась автоматически.

Используйте nim c -c --cpu:arm --os:android -d:androidNDK --noMain:on для генерации необходимых файлов исходного кода C, которые нужно включить в ваш проект Android Studio. Добавьте сгенерированные C-файлы в скрипт сборки CMake в вашем проекте Android. Затем выполните окончательную компиляцию с помощью Android Studio, которая использует Gradle для вызова CMake для компиляции проекта.

Поскольку Nim является частью библиотеки, он не может иметь собственный C-стиль main(), поэтому вам нужно будет определить свой собственный android_main и инициализировать среду Java или использовать библиотеку, например, SDL2 или GLFM. После завершения настройки Android крайне важно вызвать NimMain() для инициализации сборщика мусора Nim и выполнения основных операторов вашей программы.

proc NimMain() {.importc.}
proc glfmMain*(display: ptr GLFMDisplay) {.exportc.} =
  NimMain() # initialize garbage collector memory, types and stack

Имя NimMain может быть изменено с помощью переключателя --nimMainPrefix:prefix. Используйте --nimMainPrefix:MyLib и имя вызываемой функции — MyLibNimMain.

Кросс-компиляция для iOS

Для кросс-компиляции для iOS необходимо использовать компьютер macOS и Xcode. Обычные языки для разработки iOS — Swift и Objective-C. Оба используют LLVM и могут быть скомпилированы в объектные файлы, соединённые с C, C++ или Objective-C-кодом, сгенерированным Nim.

Используйте nim c -c --os:ios --noMain:on для генерации файлов C и их включения в ваш проект Xcode. Затем вы можете использовать Xcode для компиляции, компоновки, упаковки и подписания всего.

Поскольку Nim является частью библиотеки, он не может иметь свой собственный C-стиль main(), поэтому вам нужно определить main, который вызовет autoreleasepool и UIApplicationMain для выполнения, или использовать библиотеку, например, SDL2 или GLFM. После завершения настройки iOS крайне важно вызвать NimMain() для инициализации сборщика мусора Nim и выполнения основных операторов вашей программы.

proc NimMain() {.importc.}
proc glfmMain*(display: ptr GLFMDisplay) {.exportc.} =
  NimMain() # initialize garbage collector memory, types and stack

Примечание: "make clean" в Xcode путается с сгенерированными файлами nim.c, поэтому вам нужно очистить эти файлы вручную, чтобы выполнить чистую сборку.

Имя NimMain может быть изменено с помощью переключателя --nimMainPrefix:prefix. Используйте --nimMainPrefix:MyLib и имя вызываемой функции — MyLibNimMain.

Кросс-компиляция для Nintendo Switch

Просто добавьте --os:nintendoswitch к вашей обычной команде nim c или nim cpp и установите параметры командной строки passC и passL на значения, подобные:

nim c ... --d:nimAllocPagesViaMalloc --mm:orc --passC="-I$DEVKITPRO/libnx/include" ...
--passL="-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx"

или настройте файл nim.cfg следующим образом:

#nim.cfg
--mm:orc
--d:nimAllocPagesViaMalloc
--define:nimInheritHandles
--passC="-I$DEVKITPRO/libnx/include"
--passL="-specs=$DEVKITPRO/libnx/switch.specs -L$DEVKITPRO/libnx/lib -lnx"

Настройка devkitPro должна быть такой же, как по умолчанию, с их новым установщиком здесь для Mac/Linux или здесь для Windows.

Например, с вышеуказанной конфигурацией:

nim c --os:nintendoswitch switchhomebrew.nim

Это сгенерирует файл с именем switchhomebrew.elf, который затем можно преобразовать в файл nro с помощью инструмента elf2nro в релизе devkitPro. Примеры можно найти в репозитории nim-libnx github repo.

Есть несколько вещей, которые не работают, потому что библиотеки devkitPro их не поддерживают. Это:

1. Ожидание завершения дочернего процесса. Дочерний процесс может быть запущен, но на данный момент его нельзя ожидать, что немного затрудняет использование дочерних процессов.
2. Динамические вызовы. Операционная система Switch (Horizon) не поддерживает динамические библиотеки, поэтому dlopen/dlclose недоступны.
3. mqueue. К сожалению, нет заголовков mqueue.
4. ucontext. Также нет заголовков для этих типов. Пока нет сопрограмм :(
5. nl_types. Нет заголовков для этого.
6. Поскольку mmap не поддерживается, необходимо использовать параметр nimAllocPagesViaMalloc.

Компиляция для GPU

Компиляция для вычислений на GPU может быть выполнена с помощью --cc:nvcc для CUDA с nvcc или --cc:hipcc для графических процессоров AMD с HIP. Оба компилятора требуют сборки для C++ с nim cpp.

Вот очень простой пример CUDA ядра с использованием emit, который можно скомпилировать с помощью nim cpp --cc:nvcc --define:"useMalloc" hello_kernel.nim, предполагая, что у вас установлен CUDA toolkit.

{.emit: """
__global__ void add(int a, int b) {
  int c;
  c = a + b;
}
""".}

proc main() =
  {.emit: """
  add<<<1,1>>>(2,7);
  """.}

main()

Генерация DLL

Примечание: Те же правила применяются к lib*.so файлам shared object на UNIX. Для лучшей читабельности здесь описана только версия DLL.

Nim поддерживает генерацию DLL. Однако должен быть только один экземпляр GC на процесс/адресное пространство. Этот экземпляр содержится в nimrtl.dll. Это означает, что каждая сгенерированная DLL Nim зависит от nimrtl.dll. Для генерации файла "nimrtl.dll" используйте команду:

nim c -d:release lib/nimrtl.nim

Для ссылки на nimrtl.dll используйте команду:

nim c -d:useNimRtl myprog.nim

Дополнительные переключатели компиляции

Стандартная библиотека поддерживает всё больше useX условных определений, влияющих на реализацию некоторых функций. Этот раздел пытается дать полный список.

Дополнительные возможности

В этом разделе описаны дополнительные функции Nim, которые не указаны в руководстве по Nim. Некоторые из функций здесь имеют смысл только для генератора кода C и могут быть изменены.

Параметр LineDir

Параметр --lineDir может быть включён или выключён. Если он включён, сгенерированный код C содержит директивы #line. Это может быть полезно для отладки с помощью GDB.

Параметр StackTrace

Если включён параметр --stackTrace, сгенерированный C содержит код, который гарантирует, что будут предоставлены правильные трассировки стека, если программа аварийно завершит работу или произойдёт какое-то необработанное исключение.

Параметр LineTrace

Параметр --lineTrace подразумевает параметр stackTrace. Если он включён, сгенерированный C содержит код, который гарантирует, что при аварийном завершении работы программы или возникновении необработанного исключения будут предоставлены правильные трассировки стека с информацией о номере строки.

DynlibOverride

По умолчанию директива dynlib в Nim приводит к генерации вызовов GetProcAddress (или их Unix-аналогов) для привязки к DLL. С помощью командной строки dynlibOverride это можно предотвратить, а затем с помощью --passL статическая библиотека может быть подключена. Например, для статической ссылки на Lua на Linux эта команда может сработать:

nim c --dynlibOverride:lua --passL:liblua.lib program.nim

Параметры языка back-end

Типичное использование компилятора включает использование команд compile или c для преобразования файла .nim в один или несколько файлов .c, которые затем компилируются с помощью компилятора C платформы в статический двоичный файл. Однако есть и другие команды для компиляции в C++, Objective-C или JavaScript. Более подробную информацию можно найти в документе Интеграция Nim Backend.

Инструменты документации Nim

Nim предоставляет команду doc для генерации HTML-документации из файлов исходного кода .nim. В выходных данных будут отображаться только экспортированные символы. Более подробную информацию см. на странице документации docgen.

Интеграция Nim idetools

Nim предоставляет языковую интеграцию с внешними IDE через команду idetools. Подробности см. в документации idetools.

Nim для встраиваемых систем

Хотя стандартная конфигурация Nim нацелена на оптимальную производительность на современном ПК и операционных системах с достаточным объёмом памяти, вполне возможно запустить код Nim и большую часть стандартных библиотек Nim на небольших встраиваемых микропроцессорах с несколькими килобайтами памяти.

Хорошим началом является использование целевого оператора any вместе с менеджером памяти malloc и сборщиком мусора arc. Например:

nim c --os:any --mm:arc -d:useMalloc [...] x.nim

• --mm:arc включит управление памятью с помощью подсчёта ссылок вместо сборщика мусора по умолчанию. Это позволит Nim использовать кучу памяти, которая требуется, например, для строк и seq.
• Целевой параметр --os:any гарантирует, что Nim не зависит от каких-либо специфических функций операционной системы. Ваша платформа должна поддерживать только некоторые основные функции библиотеки ANSI C stdlib и stdio , которые должны быть доступны почти на любой платформе.
• Параметр -d:useMalloc настраивает Nim использовать только стандартные примитивы управления памятью C malloc(), free(), realloc().

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

Для платформ с очень ограниченной памятью может быть полезно передать некоторые дополнительные флаги как компилятору Nim, так и компилятору C и/или линковщику, чтобы оптимизировать сборку по размеру. Например, следующие флаги могут быть использованы при нацеливании на компилятор gcc:

--opt:size -d:lto -d:strip

Флаг --opt:size указывает Nim оптимизировать генерацию кода для уменьшения размера (с помощью компилятора C), флаги -d:lto включают оптимизацию в момент линковки в компиляторе и линковщике, флаг -d:strip удаляет символы отладки.

См. раздел Перекрёстная компиляция для инструкций по компиляции программы для вашей целевой платформы.

nimAllocPagesViaMalloc

По умолчанию аллокатор Nim основан на TLSF, этот алгоритм был разработан для встраиваемых устройств. Этот аллокатор получает блоки/страницы памяти через в настоящее время не документированный osalloc API, который обычно использует вызов POSIX mmap. На многих средах mmap недоступен, но функция C malloc есть. Вы можете использовать определение nimAllocPagesViaMalloc для использования malloc вместо mmap. nimAllocPagesViaMalloc в настоящее время поддерживается только с --mm:arc или --mm:orc. (С версии 1.6)

nimPage256 / nimPage512 / nimPage1k

Измените размер страницы для аллокатора GC Nim. Это позволяет использовать nimAllocPagesViaMalloc на устройствах с меньшим объёмом оперативной памяти. Размер страницы по умолчанию требует слишком много оперативной памяти для работы.

Рекомендованные значения:

• < 32 КБ ОЗУ использовать nimPage256
• < 512 КБ ОЗУ использовать nimPage512
• < 2 МБ ОЗУ использовать nimPage1k

Первоначальные тесты не показали значительной разницы между размерами страниц 512B или 1 КБ с точки зрения производительности или задержки. Использование nimPages256 ограничит общее количество выделяемой оперативной памяти.

nimMemAlignTiny

Устанавливает MemAlign на 4 байт, что уменьшает выравнивание памяти, чтобы лучше соответствовать некоторым встраиваемым устройствам.

Размер стека потока

API потоков Nim предоставляет простой интерфейс к более сложным функциям задач RTOS. Настройка размера стека и размера защищённого стека может быть выполнена путём задания -d:nimThreadStackSize=16384 или -d:nimThreadStackGuard=32.

В настоящее время только Zephyr, NuttX и FreeRTOS поддерживают эти настройки.

Nim для систем реального времени

См. настройки управления памятью --mm:arc или --mm:orc в MM для получения дополнительной информации.

Обработка сигналов в Nim

Язык программирования Nim не имеет понятия о механизмах обработки сигналов Posix. Однако стандартная библиотека предлагает некоторую ограниченную поддержку обработки сигналов, в частности, ошибки сегментации преобразуются в критические ошибки, которые генерируют трассировку стека. Это можно отключить с помощью переключателя -d:noSignalHandler.

Оптимизация для Nim

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

Однако иногда приходится оптимизировать. Делайте это в следующей последовательности:

1. выключите встроенный отладчик (он медленный!)
2. включите оптимизатор и отключите проверки во время выполнения
3. профилируйте свой код, чтобы найти узкие места
4. попробуйте найти лучший алгоритм
5. выполните оптимизации низкого уровня

Этот раздел может помочь вам только с последним пунктом.

Оптимизация обработки строк

Присваивание строк иногда является дорогостоящим в Nim: требуется скопировать всю строку. Однако компилятор часто достаточно умен, чтобы не копировать строки. Из-за семантики передачи аргументов, строки никогда не копируются при передаче в подпрограммы. Компилятор не копирует строки, которые являются результатом вызова процедуры, потому что вызываемая процедура возвращает новую строку в любом случае. Таким образом, эффективно делать:

var s = procA() # assignment will not copy the string; procA allocates a new
                # string already

Однако неэффективно делать:

var s = varA    # assignment has to copy the whole string into a new buffer!

Для let символов копия не всегда необходима:

let s = varA    # may only copy a pointer if it safe to do so

Компилятор оптимизирует операторы case со строками: если используется несколько различных строковых констант, для них используется схема хеширования. Поэтому код подобный этому достаточно эффективен:

case normalize(k.key)
of "name": c.name = v
of "displayname": c.displayName = v
of "version": c.version = v
of "os": c.oses = split(v, {';'})
of "cpu": c.cpus = split(v, {';'})
of "authors": c.authors = split(v, {';'})
of "description": c.description = v
of "app":
  case normalize(v)
  of "console": c.app = appConsole
  of "gui": c.app = appGUI
  else: quit(errorStr(p, "expected: console or gui"))
of "license": c.license = UnixToNativePath(k.value)
else: quit(errorStr(p, "unknown variable: " & k.key))