Немного контента

Author: EvilBeaver

.vitepress/config.mts

@@ -86,7 +86,7 @@ export default defineConfig({
             { text: 'Основы синтаксиса', link: '/learn/syntax-basics'},
             { text: 'Корпоративным пользователям', link: '/learn/enterprise'},
           ]
-        },
+        }
       ]
     },
 

docs/images/proj-structure.png

@@ -6,6 +6,108 @@
 
 Создадим пустой каталог и откроем его в VS Code с помощью меню File -> Open Folder. Этот режим открывает папку, как каталог проекта. Это основной режим разработки проектов для 1Скрипт. В нем мы работаем с содержимым папки, как с единым проектом.
 
+### Организация корневого каталога репозитория
+
 Далее, стоит определиться со структурой каталогов. Рекомендуется следующий подход:
 
-* Корень репозитория не содержит собственно кода и служэ
+* Корень репозитория не содержит собственно кода и служит контейнером для всех ресурсов, связанных с проектом: кода, тестов, документации, вспомогательных инструментов
+* Код проекта, рекомендуется размещать в подпапке src. Содержимое этой папки должно быть удобно отправлять на запуск или сборку и упаковку в дистрибутив. Желательно, чтобы в ней не было ничего лишнего, что в дистрибутив попадать не должно.
+* Тесты проекта рекомендуется размещать в папке tests
+* В папке tasks рекомендуется размещать служебные скрипты, которые помогают разработчику: запускают тесты, собирают дистрибутив, еще что-то.
+
+Также в корне проекта рекомендуется размещать манифест пакета, по которому собирается дистрибутив и [отправляется в хаб пакетов](/learn/libraries)
+
+![](/images/proj-structure.png)
+
+Файлы README и LICENSE лучше создать заранее. На начальном этапе разработки они не нужны, но когда проект будет готов к публикации, они напомнят о том, что их надо заполнить.
+
+## Заполнение манифеста
+
+Каждый пакет, будь то приложение или библиотека для переиспользования в других проектах, должна иметь файл манифеста. Это файл с именем `packagedef`, который описывает состав пакета: исходники, используемые библиотеки, название и версию, действия при установке и удалении пакета.
+
+Технически, манифест представляет собой файл скрипта и может содержать исполняемый код. Этот скрипт обрабатывается пакетным менеджером `opm` при сборке пакета.
+
+### Минимально необходимый манифест
+
+В манифесте обязательно должны быть указаны:
+
+* Имя пакета
+* Версия пакета
+* Состав пакета
+
+Как правило, также указываются зависимости, которые надо установить вместе с пакетом. На примере ниже указаны зависимости от библиотек `fs` и `asserts`.
+
+```bsl
+Описание.Имя("my-package")
+    .Версия("1.0.0")
+    .ВерсияСреды("2.0.0")
+    .ЗависитОт("fs", "1.0.0")
+    .ЗависитОт("asserts", "1.3.0")
+    .ВключитьФайл("packagedef")
+    .ВключитьФайл("src")
+    .ВключитьФайл("oscript_modules")
+    .ИсполняемыйФайл("src/my-script.os");
+```
+
+### Свойства манифеста
+
+* ВерсияСреды - минимально необходимая версия движка 1Скрипт, на которой будет работать пакет
+* ЗависитОт - указание библиотеки, которую использует наш пакет и, опционально, минимальный номер ее версии
+* ВключитьФайл - файл или каталог, который входит в состав пакета и будет включен в дистрибутив
+* ИсполняемыйФайл - если мы разрабатываем не библиотеку, а самостоятельное приложение, то здесь указываем путь к точке входа
+
+::: info Информация
+Полный перечень настроек манифеста содержится в документации к пакетному менеджеру opm.
+:::
+
+## Структура каталогов
+
+Большинство проектов не состоят из единственного файла, а разбиты на разные модули. 1Скрипт может загружать другие скрипты в виде двух сущностей: классы и модули
+
+### Класс
+Под классом понимается новый тип в системе типов приложения. Экземпляры объектов этого типа создаются через оператор **Новый**.
+
+```bsl
+    // подключаем функционал JSON
+    #Использовать json
+
+    Парсер = Новый ПарсерJSON(); // Тип ПарсерJSON объявлен в библиотеке
+```
+
+### Модуль
+
+Модуль это то же самое, что ОбщийМодуль в системе 1С:Предприятие. Модуль - это свойство в глобальном контексте, методы которого мы можем вызывать из языка.
+
+```bsl
+    // подключаем функционал JSON
+    #Использовать json
+
+    Студент = Новый Структура("Имя,Фамилия", "Иван", "Петров");
+    // Модуль "РаботаСJSON" объявлен в библиотеке и доступен благодаря директиве #Использовать
+    РаботаСJSON.ЗаписатьОбъект(Студент, "C:\students.json");
+```
+
+Стандартный загрузчик ориентируется на структуру каталогов. Внутри каталога src рекомендуется создать папки `Классы` и `Модули`. Все файлы *.os из каталога "Классы" будут подключены как классы (и их можно создать через `Новый`), а файлы *.os из каталога "Модули" - как общие модули.
+
+:::info Информация
+Подробности и принцип загрузки скриптов, а также модуль загрузчика описаны в разделе [Библиотеки](/learn/libraries)
+:::
+
+### Подключение собственных модулей пакета
+
+Для того, чтобы загрузчик отработал, необходимо в стартовом скрипте написать директиву импорта папки, в которой лежат подкаталоги `Классы` и `Модули`.
+
+Например, пусть наш стартовый скрипт `my-script.os` лежит в каталоге src корня репозитория. Рядом с ним лежат 2 каталога `Классы` и `Модули`. В них расположены файлы классов и модулей соответственно. Для того, чтобы `my-script.os` увидел эти классы и модули, нам надо отправить в загрузчик "приказ" о загрузке библиотеки. Однако, в данном случае, библиотекой являемся мы сами, наш собственный проект и мы сами себя должны импортировать в пространство стартового скрипта `my-script.os`.
+
+Делается это с помощью директивы `Использовать`, в качестве аргумента которой мы указываем текущий каталог (точку)
+
+```bsl
+// Файл my-script.os
+// Импортируем текущую папку (в ней лежат подпапки Классы и Модули, которые обработает загрузчик)
+
+#Использовать "."
+
+// Использование модуля
+Сообщить(МойМодуль.КакойТоМетодМодуля())
+
+```