andrey
9588b48105
Reviewed-on: #194 Co-authored-by: andrey.bychkov <andrey@signalmodelling.ru> Co-committed-by: andrey.bychkov <andrey@signalmodelling.ru>
158 lines
5.5 KiB
Markdown
158 lines
5.5 KiB
Markdown
# Platform-Independent Primitives library
|
|
|
|
## Introduction
|
|
|
|
Low-level C++ library that covers next areas:
|
|
* Strings
|
|
* Console IO
|
|
* Threads
|
|
* Timers
|
|
* Events
|
|
* Various IO devices
|
|
* Mathematics (FFT with libfftw3)
|
|
* Cryptography (libsodium)
|
|
* Compression (zlib)
|
|
* Resources
|
|
* Metaprogramming
|
|
|
|
## CMake
|
|
|
|
This library tightly integrated with CMake by providing some macro:
|
|
|
|
* `pip_code_model(<out_var> file0 [file1 ...] [OPTIONS opt0 [opt1 ...] ] [ABSOLUTE])`
|
|
Generate code model files for source files file0 [file1 ...].
|
|
|
|
Options you can see by exec "pip_cmg -h".
|
|
If not ABSOLUTE source files will be prepended by ${CMAKE_CURRENT_SOURCE_DIR}.
|
|
You should add ${<out_var>} to your target.
|
|
|
|
* `pip_resources(<out_var> file)`
|
|
|
|
Generate C++ files for resource file.
|
|
You should add ${<out_var>} to your target.
|
|
|
|
## Documentation
|
|
|
|
[🇺🇸 Online documentation](https://shstk.ru/pip/html/en/index.html)
|
|
|
|
[🇺🇸 Qt-help](https://shstk.ru/pip/pip_en.qch)
|
|
|
|
[🇷🇺 Онлайн документация](https://shstk.ru/pip/html/ru/index.html)
|
|
|
|
[🇷🇺 Qt-help](https://shstk.ru/pip/pip_ru.qch)
|
|
|
|
## Основные опции сборки
|
|
|
|
### Стандартные опции (option())
|
|
| Опция | Описание | По умолчанию |
|
|
|-------|----------|--------------|
|
|
| `ICU` | ICU support для конвертации кодовых страниц | ON (кроме Win/Android/Apple) |
|
|
| `STD_IOSTREAM` | Поддержка std::iostream операторов | OFF |
|
|
| `INTROSPECTION` | Сборка с интроспекцией | OFF |
|
|
| `TESTS` | Сборка тестов | OFF |
|
|
| `COVERAGE` | Сборка с информацией о покрытии | OFF |
|
|
| `PIP_FFTW_F` | Поддержка FFTW для float | ON |
|
|
| `PIP_FFTW_L` | Поддержка FFTW для long double | ON |
|
|
| `PIP_FFTW_Q` | Поддержка FFTW для quad double | OFF |
|
|
|
|
### Опции модулей (PIP_BUILD_*)
|
|
| Опция | Модуль |
|
|
|-------|--------|
|
|
| `PIP_BUILD_CONSOLE` | console |
|
|
| `PIP_BUILD_CRYPT` | crypt (требует libsodium) |
|
|
| `PIP_BUILD_COMPRESS` | compress (требует zlib) |
|
|
| `PIP_BUILD_USB` | usb |
|
|
| `PIP_BUILD_FFTW` | fftw |
|
|
| `PIP_BUILD_OPENCL` | opencl |
|
|
| `PIP_BUILD_IO_UTILS` | io_utils |
|
|
| `PIP_BUILD_CLIENT_SERVER` | client_server |
|
|
| `PIP_BUILD_CLOUD` | cloud |
|
|
| `PIP_BUILD_LUA` | lua |
|
|
| `PIP_BUILD_HTTP_CLIENT` | http_client (требует libcurl) |
|
|
| `PIP_BUILD_HTTP_SERVER` | http_server (требует libmicrohttpd) |
|
|
|
|
### Дополнительные переменные
|
|
| Переменная | Описание |
|
|
|------------|----------|
|
|
| `PIP_BUILD_DEBUG` | Сборка debug версии |
|
|
| `PIP_FREERTOS` | Режим сборки для FreeRTOS |
|
|
| `CROSSTOOLS` | Собрать инструменты кросс-сборки под хостовую систему (pip_cmg, pip_rc, ...) |
|
|
| `LOCAL` | Локальная установка (bin/lib/include) |
|
|
| `PIP_CONTAINERS_MIN_ALLOC` | Переопределить минимальный размер аллокации контейнеров |
|
|
| `PIP_CONTAINERS_MAX_POT_ALLOC` | Переопределить максимальный размер дополнительной аллокации (поддерживает X_KiB, X_MiB) |
|
|
|
|
### Примеры использования
|
|
```bash
|
|
# Базовая сборка с тестами
|
|
cmake -B build -DTESTS=ON
|
|
|
|
# Сборка с покрытием и ICU
|
|
cmake -B build -DTESTS=ON -DCOVERAGE=ON -DICU=ON
|
|
|
|
# Отключение отдельных модулей
|
|
cmake -B build -DPIP_BUILD_CRYPT=OFF -DPIP_BUILD_OPENCL=OFF
|
|
|
|
# Переопределение параметров контейнеров
|
|
cmake -B build -DPIP_CONTAINERS_MIN_ALLOC=64
|
|
|
|
# Локальная установка
|
|
cmake -B build -DLOCAL=ON
|
|
```
|
|
|
|
## PIP Dependencies
|
|
|
|
### Встроенные (included in 3rd/)
|
|
|
|
| Библиотека | Назначение | Модуль PIP |
|
|
|------------|------------|------------|
|
|
| **PCRE2** | Регулярные выражения | main (internal) |
|
|
| **BLAKE2** | Хеширование | main (internal) |
|
|
| **SipHash** | Хеширование | main (internal) |
|
|
| **Lua** | Lua scripting | lua |
|
|
| **LuaBridge** | Lua bindings | lua |
|
|
|
|
### Внешние (системные)
|
|
|
|
| Библиотека | Опция | Модуль PIP |
|
|
|------------|-------|------------|
|
|
| **ICU** | `-DICU=ON` | main (string conversion) |
|
|
| **zlib** | `PIP_BUILD_COMPRESS` | compress |
|
|
| **libsodium** | `PIP_BUILD_CRYPT` | crypt, io_utils, cloud |
|
|
| **libusb** | `PIP_BUILD_USB` | usb |
|
|
| **FFTW3** (+ threads) | `PIP_BUILD_FFTW` | fftw |
|
|
| **OpenCL** | `PIP_BUILD_OPENCL` | opencl |
|
|
| **libmicrohttpd** | `PIP_BUILD_HTTP_SERVER` | http_server |
|
|
| **libcurl** | `PIP_BUILD_HTTP_CLIENT` | http_client |
|
|
|
|
### Опциональные (тесты/документация)
|
|
|
|
| Инструмент | Назначение |
|
|
|------------|------------|
|
|
| **Google Test** | Тестирование (fetched automatically) |
|
|
| **Doxygen** | Генерация документации |
|
|
|
|
|
|
### Схема зависимостей модулей
|
|
|
|
```
|
|
main (core)
|
|
├── PCRE2 (встроен)
|
|
├── BLAKE2 (встроен)
|
|
├── SipHash (встроен)
|
|
└── ICU (опционально)
|
|
|
|
console → main
|
|
compress → zlib
|
|
crypt → libsodium
|
|
usb → libusb
|
|
fftw → FFTW3
|
|
opencl → OpenCL
|
|
io_utils → [crypt, если доступен]
|
|
client_server → io_utils
|
|
cloud → io_utils, crypt
|
|
lua → Lua (встроен), LuaBridge (встроен)
|
|
http_server → libmicrohttpd
|
|
http_client → libcurl
|
|
```
|
|
|