Merge pull request EvilBeaver#1669 from johnnyshut/docs/update-202604

docs: актуализация документации проекта (.NET 8, корректные пути, дописанные разделы)

Author: EvilBeaver

README-EN.md

@@ -57,50 +57,97 @@ The OneScript distribution already includes a set of the most commonly used pack
 
 ## Preparation
 
-Links to distributions are provided below, however, please note that links may change over time and their relevance is not guaranteed. You need dotnet SDK and C++ compiler, which can be downloaded from anywhere you can find.
+To build the project you need:
 
-* Install [MS BuildTools](https://visualstudio.microsoft.com/ru/thank-you-downloading-visual-studio/?sku=buildtools&rel=16), when installing enable targeting for .net6, .net4.8, install C++ compiler.
+* [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) (the project's target framework is `net8.0`).
+* A C++ compiler — only required to build the native bridge `ScriptEngine.NativeApi` (support for native add-ins compatible with the 1C NativeApi). On Windows the easiest way to get one is to install [MS Build Tools](https://visualstudio.microsoft.com/visual-studio-build-tools/) or Visual Studio with the "Desktop development with C++" workload. If a C++ compiler is not available, see the `NoCppCompiler` parameter below.
+
+> Distribution links may change over time, their relevance is not guaranteed.
 
 ## Build
 
-Launch Developer Command Prompt (will appear in the Start menu after installing MSBuildTools or Visual Studio). Navigate to the OneScript repository directory. The following are commands in the Developer Command Prompt console.
-Build is performed using msbuild. Targets:
+The build is driven by MSBuild via the `Build.csproj` script in the repository root. Commands can be run with `msbuild` (Developer Command Prompt installed together with MS Build Tools/Visual Studio) or with `dotnet msbuild` (cross-platform).
+
+Main targets:
 
-* CleanAll - clean previous build results
-* BuildAll - prepare files for distribution
-* MakeCPP;MakeFDD;MakeSCD;BuildDebugger - separate build targets for preparing different types of distributions
-* PrepareDistributionFiles - build full distribution packages (including libraries)
-* PackDistributions - prepare ZIP archives for distribution
-* CreateNuget - create packages for publishing to NuGet
+* `CleanAll` — clean previous build results;
+* `BuildAll` — build binary files for distribution (FDD, SCD, debugger; native components are also built when a C++ compiler is available);
+* `MakeCPP`, `MakeFDD`, `MakeSCD`, `BuildDebugger` — individual targets that build specific parts of the distribution;
+* `GatherLibrary` — download and stage the base set of libraries (`opm`, `asserts`, `logos`, `fs`, `tempfiles`, `cli`);
+* `PrepareDistributionFiles` — build full distribution contents (including libraries and documentation);
+* `PackDistributions` — pack the distribution contents into ZIP archives for all supported platforms;
+* `BuildDocumentation` — generate the platform reference (markdown + json);
+* `CreateNuget` / `PublishNuget` — build and publish NuGet packages;
+* `Test` (`UnitTests`, `ScriptedTests`) — run unit and acceptance (BSL) tests.
 
 **Build parameters**
 
-* VersionPrefix - release number prefix, its main part, for example, 2.0.0
-* VersionSuffix - version suffix, which usually acts as an arbitrary versioning suffix according to semver, for example, beta-786 (optional)
-* NoCppCompiler - if True - C++ compiler is not installed, C++ components (NativeApi support) will not be added to the build
+* `VersionPrefix` — main part of the release number, for example `2.0.0` (defaults to `2.0.0`);
+* `VersionSuffix` — optional SemVer suffix, for example `beta-786`;
+* `NoCppCompiler` — when set to `True`, native C++ components (NativeApi) are not built and not included in the distribution (use it when no C++ compiler is installed);
+* `Configuration` — build configuration, defaults to `Release`. For a debug build on Linux use `LinuxDebug`.
 
-All distribution files will be placed in the `built` directory at the root of the 1Script repository
+All build artifacts are placed in the `built` directory at the repository root.
 
 ### Building distribution contents in a separate directory
 
 ```bat
-msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles
 ```
 
 ### Building with manual version specification
 
 ```bat
-msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:VersionPrefix=2.0.0
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:VersionPrefix=2.0.0
 ```
 
 ### Building ZIP distributions
 
 ```bat
-msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles;PackDistributions /p:VersionPrefix=2.0.0 /p:VersionSuffix=preview223
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles;PackDistributions /p:VersionPrefix=2.0.0 /p:VersionSuffix=preview223
+```
+
+### Building without C++ components (no NativeApi)
+
+```bat
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:NoCppCompiler=True
 ```
 
 ### Documentation generation
 
 ```bat
-msbuild Build.csproj /t:BuildDocumentation
+dotnet msbuild Build.csproj /t:BuildDocumentation
 ```
+
+# Testing
+
+The project has two layers of tests:
+
+* **C# unit tests** — located in `src/Tests/*` (xUnit/NUnit). Run them via `dotnet test` in the corresponding test project directory or all at once:
+  ```bat
+  dotnet msbuild Build.csproj /t:UnitTests
+  ```
+* **BSL acceptance tests** — located in the `tests/` directory and executed by `testrunner.os` against a freshly built `oscript`. The repository includes wrapper scripts:
+  ```bat
+  rem Windows
+  tests\run-bsl-tests.cmd src\oscript\bin\Debug\net8.0\oscript.exe
+  ```
+
+  ```bash
+  # Linux/macOS
+  tests/run-bsl-tests.sh src/oscript/bin/Debug/net8.0/oscript
+  ```
+
+  Before running the acceptance tests, build `oscript`:
+  ```bat
+  dotnet build src/oscript/oscript.csproj
+  ```
+
+# Developer documentation
+
+If you want to contribute to the project, take a look at the additional documents in the [`docs/`](docs/) directory:
+
+* [`docs/developer_docs.md`](docs/developer_docs.md) — project architecture, solution layout and guided tour of the source code.
+* [`docs/contexts.md`](docs/contexts.md) — a practical guide to adding BSL contexts, methods, properties and global functions.
+* [`CODESTYLE.md`](CODESTYLE.md) — C# code style requirements.
+

README.md

@@ -57,50 +57,96 @@ OneScript позволяет создавать и выполнять текст
 
 ## Подготовка
 
-Ниже приведены ссылки на дистрибутивы, однако, учтите, что ссылки могут меняться со временем и их актуальность не гарантируется. Нужен dotnet SDK и компилятор C++, скачать можно из любого места, которое нагуглится.
+Для сборки потребуется:
 
-* Установить [MS BuildTools](https://visualstudio.microsoft.com/ru/thank-you-downloading-visual-studio/?sku=buildtools&rel=16), при установке включить таргетинг на .net6, .net4.8, установить компилятор C++.
+* [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) (целевой фреймворк проекта — `net8.0`).
+* Компилятор C++ — нужен только для сборки нативного моста `ScriptEngine.NativeApi` (поддержка внешних компонент стандарта 1С NativeApi). На Windows проще всего получить его, поставив [MS Build Tools](https://visualstudio.microsoft.com/visual-studio-build-tools/) или Visual Studio с компонентом «Разработка классических приложений на C++». Если C++ компилятора нет, см. параметр `NoCppCompiler` ниже.
+
+> Ссылки на дистрибутивы могут меняться со временем, их актуальность не гарантируется.
 
 ## Сборка
 
-Запустить Developer Command Prompt (появится в меню Пуск после установки MSBuildTools или Visual Studio). Перейти в каталог репозитория OneScript. Далее приведены команды в консоли Developer Command Prompt
-Сборка выполняется с помощью msbuild. Таргеты:
+Сборка выполняется с помощью MSBuild и сценария `Build.csproj` в корне репозитория. Команды можно запускать как через `msbuild` (Developer Command Prompt после установки MS Build Tools/Visual Studio), так и через `dotnet msbuild` (кросс-платформенно).
+
+Основные таргеты:
 
-* CleanAll - очистка результатов предыдущих сборок
-* BuildAll - подготовить файлы для поставки
-* MakeCPP;MakeFDD;MakeSCD;BuildDebugger - отдельные таргеты сборки для подготовки разных типов поставки
-* PrepareDistributionFiles - сборка полных пакетов поставки (включая библиотеки)
-* PackDistributions - подготовка ZIP архивов поставки
-* CreateNuget - создать пакеты для публикации в NuGet
+* `CleanAll` — очистка результатов предыдущих сборок;
+* `BuildAll` — собрать бинарные файлы для поставки (FDD, SCD, отладчик; при наличии C++ — нативные компоненты);
+* `MakeCPP`, `MakeFDD`, `MakeSCD`, `BuildDebugger` — отдельные таргеты сборки разных частей поставки;
+* `GatherLibrary` — скачать и сложить базовый набор библиотек (`opm`, `asserts`, `logos`, `fs`, `tempfiles`, `cli`);
+* `PrepareDistributionFiles` — собрать полные содержимые дистрибутивов (вкл. библиотеки и документацию);
+* `PackDistributions` — упаковать содержимое в ZIP-архивы под все поддерживаемые платформы;
+* `BuildDocumentation` — сгенерировать справку по платформе (markdown + json);
+* `CreateNuget` / `PublishNuget` — собрать и опубликовать NuGet-пакеты;
+* `Test` (`UnitTests`, `ScriptedTests`) — прогнать модульные и приёмочные (BSL) тесты.
 
 **Параметры сборки**
 
-* VersionPrefix - префикс номера релиза, его основная часть, например, 2.0.0
-* VersionSuffix - суффикс номера, который обычно выступает в качестве произвольного суффикса версионирования по semver, например, beta-786 (необязателен)
-* NoCppCompiler - если True - не установлен компилятор C++, в сборку не будут добавлены компоненты C++ (поддержка NativeApi)
+* `VersionPrefix` — основная часть номера релиза, например `2.0.0` (по умолчанию `2.0.0`);
+* `VersionSuffix` — необязательный suffix по SemVer, например `beta-786`;
+* `NoCppCompiler` — если `True`, нативные компоненты C++ (NativeApi) не собираются и не включаются в дистрибутив (используйте, если компилятор C++ не установлен);
+* `Configuration` — конфигурация сборки, по умолчанию `Release`. Для отладочной сборки на Linux используется `LinuxDebug`.
 
-Все поставляемые файлы будут размещены в каталоге `built` в корне репозитория 1Script
+Все артефакты сборки размещаются в каталоге `built` в корне репозитория.
 
 ### Сборка содержимого дистрибутивов в отдельном каталоге
 
 ```bat
-msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles
 ```
 
 ### Сборка с ручным указанием версии
 
 ```bat
-msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:VersionPrefix=2.0.0
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:VersionPrefix=2.0.0
 ```
 
 ### Сборка ZIP-дистрибутивов
 
 ```bat
-msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles;PackDistributions /p:VersionPrefix=2.0.0 /p:VersionSuffix=preview223
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles;PackDistributions /p:VersionPrefix=2.0.0 /p:VersionSuffix=preview223
+```
+
+### Сборка без C++-компонент (без NativeApi)
+
+```bat
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:NoCppCompiler=True
 ```
 
 ### Генерация документации
 
 ```bat
-msbuild Build.csproj /t:BuildDocumentation
-```
+dotnet msbuild Build.csproj /t:BuildDocumentation
+```
+
+# Тестирование
+
+В проекте есть два уровня тестов:
+
+* **Модульные тесты на C#** — расположены в `src/Tests/*` (xUnit/NUnit), запускаются через `dotnet test` в каталоге соответствующего тестового проекта или одной командой:
+  ```bat
+  dotnet msbuild Build.csproj /t:UnitTests
+  ```
+* **Приёмочные тесты на BSL** — расположены в каталоге `tests/` и запускаются через `testrunner.os` на свежесобранном `oscript`. Для удобства в репозитории есть скрипты-обёртки:
+  ```bat
+  rem Windows
+  tests\run-bsl-tests.cmd src\oscript\bin\Debug\net8.0\oscript.exe
+  ```
+
+  ```bash
+  # Linux/macOS
+  tests/run-bsl-tests.sh src/oscript/bin/Debug/net8.0/oscript
+  ```
+
+  Перед запуском приёмочных тестов нужно собрать `oscript`:
+  ```bat
+  dotnet build src/oscript/oscript.csproj
+  ```
+
+# Документация для разработчиков
+
+Если вы хотите контрибьютить в проект, познакомьтесь с дополнительными документами в каталоге [`docs/`](docs/):
+
+* [`docs/developer_docs.md`](docs/developer_docs.md) — архитектура проекта, состав решения и навигация по исходному коду.
+* [`docs/contexts.md`](docs/contexts.md) — практическое руководство по добавлению BSL-контекстов, методов, свойств и глобальных функций.
+* [`CODESTYLE.md`](CODESTYLE.md) — требования к стилю кода на C#.