Merge pull request #14 from deryugina/master

Fixed "embox_quick_start" doc

Author: anton-bondarev

en/embox_quick_start_en.md

@@ -1,4 +1,3 @@
-
 # Quick start
 It’s better to get started with Embox running on QEMU emulator, which supports different CPU architectures.
 
@@ -7,21 +6,21 @@ Clone git repository:
 ```
     $ git clone https://github.com/embox/embox
 ```
-Or download as an archive:
-```
-    [https://github.com/embox/embox/releases](https://github.com/embox/embox/releases/)
-```
+Or download as an archive [https://github.com/embox/embox/releases](https://github.com/embox/embox/releases).
+
 ## Work on Windows or MacOS
 ### Please follow the next recommendations:
 Download an actual version of PowerShell:
-```
-    [How to download PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3/)
-```
+
+[How to download PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3/)
+
 Open PowerShell as an administrator and install WSL2 (please pay your attention to the demands on Windows version):
+
+[How to install WSL2](https://learn.microsoft.com/en-us/windows/wsl/install-manual)
 ```
-    [How to install WSL2](https://learn.microsoft.com/en-us/windows/wsl/install-manual)
+    Before the next step upgrade WSL1 to WSL2 if you did'nt do this(the instruction is in a link above).
+    In other way Embox won't run on Windows.
 ```
-Before the next step upgrade WSL1 to WSL2 if you did'nt do this(the instruction is in a link above). In other way Embox won't run on Windows.
 
 ### Download Ubuntu from Microsoft Store
 Check yout version of WSL the next way: insert the command below in PowerShell:
@@ -57,9 +56,9 @@ Run the next three commands
 ```
 P.S.: If you have any problems with running Embox on Windows -- please check a correctness of the inserted commands.
 If it's correct -- you can use the recommendations from the article(the link is below):
-```
-    [How to solve problems with WSL](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting)
-```
+
+[How to solve problems with WSL](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting)
+
 
 ## Enviroment Settings
 Minimal required packages: *make*, *gcc*, (cross-compiler for target platform. see "Cross-compiler installation").
@@ -73,11 +72,10 @@ For Debian/Ubuntu:
 ```
 For Arch:
 ```
-    sudo pacman -S make gcc-multilib cpio qemu
+    $ sudo pacman -S make gcc-multilib cpio qemu
 ```
 
 ## Cross-compiler installation
-
 ***x86***:
 ```
     $ sudo apt-get install gcc
@@ -101,14 +99,13 @@ Extract files from archive and set *PATH* enviroment variable:
 
 ***SPARC, Microblaze, MIPS, PowerPC, MSP430***:
 You can try to use some cross-compiler based on gcc in case if you already have a suitable one.
+
 But it would be better if you will use our project for cross-compiler installation:
-```
-    [https://github.com/embox/crosstool](https://github.com/embox/crosstool)
-```
+[https://github.com/embox/crosstool](https://github.com/embox/crosstool)
+
 You can use already ready-to-use archives from:
-```
-    [https://github.com/embox/crosstool/releases](https://github.com/embox/crosstool/releases)
-```
+[https://github.com/embox/crosstool/releases](https://github.com/embox/crosstool/releases)
+
 Or you can build cross-compiler with the script in the project's root folder:
 ```
     $ ./crosstool.sh ARCH
@@ -157,17 +154,18 @@ Now you are able to run Embox:
 ```
 Console output example:
 ```
-Embox kernel start
-    unit: initializing embox.kernel.task.task_resource: done
-    unit: initializing embox.mem.vmem_alloc: done
+    Embox kernel start
+        unit: initializing embox.kernel.task.task_resource: done
+        unit: initializing embox.mem.vmem_alloc: done
 ```
 If all unit tests passed successfully and all modules loaded, then command prompt will appear.
 Now you can execute commands included in the configuration (`mods.conf`). You can start with ***help*** command which prints list of available commands.
 
 Press ***ctrl+’A’*** and then `***x***` to exit from Qemu.
 
 ## Preliminaries to Mybuild build system
-Embox is modular and configurable. Declarative program language "Mybuild" has been developed for these features. Mybuild allows to describe both single modules and whole target system.
+Embox is modular and configurable. Declarative program language "Mybuild" has been developed for these features. 
+Mybuild allows to describe both single modules and whole target system.
 
 A module is a base concept for build system. A module description contains: source files list, options which can be set for the module during configuration, and dependences list.
 
@@ -272,3 +270,14 @@ After running that QEMU waits for a connection from a gdb-client. Run gdb in the
 The system starts to load.
 
 At any moment in gdb terminal you can type <kbd>ctrl + C</kbd> and see the stack of the current thread (`backtrace`) or set breakpoints (`break <function name>`, `break <file name>:<line number>`).
+
+## Connection of external repository
+Embox allows to connect external repo to modules and templates. It's enough to specify root directory of repository for this purpose:
+```
+    make ext_conf EXT_PROJECT_PATH=<your projects path>
+```
+To make templates visible through "make confload" and "make confload-" calls, connected repo has to have the next folder-structure:
+```
+    <root_folder>/<project_name>/templates
+```
+Modules can be in random folders. Search is carried out, using *Mybuild* and **.my* files.

en/embox_supported_platforms_en.md

@@ -7,4 +7,3 @@ Embox supports several popular hardware platforms based on ARM chip:
 * STM32 MCU Eval Tools
 * Raspberry Pi
 * BeagleBoard
-

en/embox_supported_platforms_arm_en.md renamed to en/platforms/embox_supported_platforms_arm_en.md

@@ -0,0 +1,12 @@
+# Supported plaftorms
+
+Embox supports several CPU architectures:
+* ARM
+* x86
+* SPARC
+* DLX (Microblaze)
+* MIPS
+* PPC (PowerPC)
+* E2k (Elbrus)
+
+There is a support for several hardware (real or virtual) platforms based on each CPU architectures. It's requred to install own developer enviroment (cross-compiler and gdb) as described in "Cross-compiler installation"

en/platforms/embox_supported_platforms_en.md

@@ -21,5 +21,3 @@ For running you should execute `auto_qemu` script:
         $ ./scripts/qemu/auto_qemu
 ```
 The script parses config files from `conf/` folder and starts `qemu` with corresponded arguments.
-
-

en/embox_supported_platforms_qemu_en.md renamed to en/platforms/embox_supported_platforms_qemu_en.md

@@ -7,4 +7,3 @@ Embox supports:
 * qemu-system-i386
 * Load with GRUB
 * BifferBoard
-

en/embox_supported_platforms_x86_en.md renamed to en/platforms/embox_supported_platforms_x86_en.md

@@ -6,30 +6,23 @@
 ```
     $ git clone https://github.com/embox/embox
 ```
-Либо скачиваем архивом из [https://github.com/embox/embox/releases](https://github.com/embox/embox/releases)
+Либо скачиваем архивом из [https://github.com/embox/embox/releases](https://github.com/embox/embox/releases).
 
 ## Запуск в Windows (и MacOS)
-
 ### Выполните следующие шаги:
-
-Скачайте актуальную версию PowerShell
+Скачайте актуальную версию PowerShell:
 
 [Алгоритм скачивания PowerShell для Windows](https://learn.microsoft.com/ru-ru/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.3)
 
-
-Зайдите в PowerShell под именем администратора и установите WSL2 (обратите внимание на требования к версии Windows)
+Зайдите в PowerShell под именем администратора и установите WSL2 (обратите внимание на требования к версии Windows):
 
 [Алгоритм установки WSL2](https://learn.microsoft.com/ru-ru/windows/wsl/install-manual)
-
-
 ```
-Перед тем как перейти к следующему шагу обязательно обновите WSL1 до WSL2
-(инструкция по ссылкам выше), в противном случае Embox не запустится под Windows
+    Перед тем как перейти к следующему шагу обязательно обновите WSL1 до WSL2
+    (инструкция по ссылкам выше), в противном случае Embox не запустится под Windows.
 ```
 
-Скачайте Ubuntu из Microsoft Store
-
-
+### Скачайте Ubuntu из Microsoft Store
 Убедитесь, что у Вас стоит WSL версии 2, для этого введите в PowerShell команду:
 ```
     wsl -l -v
@@ -45,12 +38,11 @@
     sudo apt-get install python3
     sudo apt-get install python-is-python3
 ```
-
 Клонируйте себе версию проекта (используйте https или ssh):
-
-   git clone <https://github.com/embox/embox.git>
-   git clone <[email protected]:embox/embox.com>
-
+```
+    git clone <https://github.com/embox/embox.git>
+    git clone <[email protected]:embox/embox.com>
+```
 
 Зайдите в папку проекта:
 ```
@@ -68,11 +60,11 @@
 [Устранение неполадок WSL](https://learn.microsoft.com/ru-ru/windows/wsl/troubleshooting)
 
 
-
 ## Настройка окружения
-Необходимые пакеты: make, gcc (кросс-компилятор под выбранную архитектуру,  см. “Установка кросс-компилятора”).
-Дополнительные пакеты (рекомендуется установить сразу): build-essential, gcc-multilib, curl, libmpc-dev, python.
-Пример установки для Debian:
+Необходимые пакеты: **make**, **gcc** (кросс-компилятор под выбранную архитектуру,  см. “Установка кросс-компилятора”).
+Дополнительные пакеты (рекомендуется установить сразу): **build-essential**, **gcc-multilib**, **curl**, **libmpc-dev**, **python**.
+
+Пример установки для Ubuntu/Debian:
 ```
     $ sudo apt-get install make gcc \
         build-essential gcc-multilib \
@@ -84,29 +76,31 @@
 ```
 
 ## Установка кросс-компилятора 
-### x86:
+***x86***:
 ```
      $ sudo apt-get install gcc
 ```
-Обычно эти пакеты уже установлены в Вашей ОС, но на всякий случай стоит это проверить. Вам также понадобится *gcc-multilib*. Обратите внимание, что требуется установить другие пакеты, если Вы уже настроили окружение на Windows и MacOS самостоятельно.
+Обычно эти пакеты уже установлены в Вашей ОС, но на всякий случай стоит это проверить. Вам также понадобится *gcc-multilib*.
+Обратите внимание, что требуется установить другие пакеты, если Вы уже настроили окружение на Windows и MacOS самостоятельно.
 
 ### ARM:
 ```
      $ sudo apt install arm-none-eabi-gcc
 ```
-Или для Debian
+Или для Debian:
 ```
     $ sudo apt install gcc-arm-none-eabi
 ```
-Вы можете также скачать архив с набором ARM-инструментов(тулчейном) по ссылке: [https://launchpad.net/gcc-arm-embedded](https://launchpad.net/gcc-arm-embedded), а затем распаковать архив и настроить переменную окружения *PATH*:
+Вы можете также скачать архив с набором ARM-инструментов(тулчейном) по ссылке: [https://launchpad.net/gcc-arm-embedded](https://launchpad.net/gcc-arm-embedded).
+Затем нужно распаковать архив и настроить переменную окружения *PATH*:
 ```
    $ export PATH=$PATH:<путь к тулчейну>/gcc-arm-none-eabi-<version>/bin
 ```
 
 ### SPARC, Microblaze, MIPS, PowerPC, MSP430:
 Для этих архитектур можно воспользоваться нашим проектом по сборке кросс-компилятора: [https://github.com/embox/crosstool](https://github.com/embox/crosstool).
 
-Также можно скачать последнюю версию готового к использованию архива отсюда: [https://github.com/embox/crosstool/releases](https://github.com/embox/crosstool/releases).
+Также можно скачать последнюю версию архива отсюда: [https://github.com/embox/crosstool/releases](https://github.com/embox/crosstool/releases).
 
 Или собрать его, выкачав скрипты из репозитория с помощью команды:
 ```
@@ -133,6 +127,7 @@ QEMU может быть установлен следующим способо
    $ make confload-<ARCH>/qemu
 ```
 Где <ARCH>: x86, arm, mips, ppc, sparc, microblaze.
+
 Пример под x86:
 ```
     $ make confload-x86/qemu
@@ -146,6 +141,7 @@ QEMU может быть установлен следующим способо
     $ make (-jN)
 ```
 Где *-j* -- это опция *make*, а *N* -- это количество параллельных процессов.
+
 Пример:
 ```
     $ make -j4
@@ -154,7 +150,6 @@ QEMU может быть установлен следующим способо
 ```
     $ ./scripts/qemu/auto_qemu
 ```
-
 Пример вывода в консоль:
 ```
 Embox kernel start
@@ -163,10 +158,12 @@ Embox kernel start
     ...
 ```
 Если все unit-тесты прошли успешно, и система загружена, появится консоль, в которой можно выполнять команды. Начать можно с команды ***'help'*** которая выведет список доступных команд для вашей конфигурации.
+
 Для выхода из эмулятора qemu нажмите последовательно: ***ctrl+’A’***, затем ***‘x’***.
 
 ## Особенности системы сборки Mybuild
-***Embox*** - модульная и настраиваемая система. Для этих целей был разработан декларативный язык описания ***Mybuild***. Он позволяет описывать как отдельные единицы системы (модули), так и всю систему в целом.
+***Embox*** - модульная и настраиваемая система. Для этих целей был разработан декларативный язык описания ***Mybuild***.
+Он позволяет описывать как отдельные единицы системы (модули), так и всю систему в целом.
 
 ***Модуль*** является базовым понятием для системы сборки. Он содержит: список файлов, относящихся к данному модулю; параметры, которые можно задать модулю в момент конфигурации; список зависимостей.
 
@@ -207,7 +204,6 @@ Embox kernel start
     $ mkdir src/cmds/hello_world
 ```
 * Создать файл с исходным кодом программы ***src/cmds/hello_world/hello_world.c*** со следующим содержанием:
-
 ```
         #include <stdio.h>
 
@@ -216,7 +212,6 @@ Embox kernel start
         }
 ```
 * Создать файл ***src/cmds/hello_world/Mybuild*** с описанием Вашего модуля:
-
 ```
         package embox.cmd
 
@@ -227,22 +222,18 @@ Embox kernel start
         }
 ```
 * Добавить программу в файл конфигурации *conf/mods.conf*:
-
 ```
         include embox.cmd.hello_world
 ```
 * Собрать Embox:
-
 ``` 
         $ make
 ```
 * Запустить Embox:
-
 ```
         $ ./scripts/qemu/auto_qemu
 ```
 * Наберите **help** в консоли Embox, чтобы проверить, появилась ли **hello_world** в списке команд, и Вы увидите:
-
 ```
         root@embox:/#hello_world 
         Hello, world!
@@ -251,7 +242,6 @@ Embox kernel start
 
 ### Файл описания модуля
 Разберем немного подробнее файл описания модуля.
-
 ```
         package embox.cmd
 
@@ -265,21 +255,23 @@ Embox kernel start
 
 Строка ***source "hello_world.c"*** содержит названия необходимых для сборки модуля файлов.
 
-В строке ***@Cmd(name = "hello_world", help="First Embox application")*** задается атрибут модуля. В первую очередь модуль будет представлять из себя приложение, а во вторую -- устанавливает имя, с помощью которого это приложение можно вызвать. И наконец, устанавливается строка, которая будет отображаться при вызове команды ***'help'***.
+В строке ***@Cmd(name = "hello_world", help="First Embox application")*** задается атрибут модуля.
+В первую очередь модуль будет представлять из себя приложение, а во вторую -- устанавливает имя, с помощью которого это приложение можно вызвать.
+И наконец, устанавливается строка, которая будет отображаться при вызове команды ***'help'***.
 
 Строка ***@AutoCmd*** показывает, что в приложении есть стандартная функция входа в приложение ***main()***, которая будет заменена на другой символ в процессе сборки.
 
 ## Отладка
 Для отладки можно использовать тот же 'auto_qemu' скрипт, добавив флаги *-s -S -no-kvm*:
 ```
-$ sudo ./scripts/qemu/auto_qemu -s -S -no-kvm
+    $ sudo ./scripts/qemu/auto_qemu -s -S -no-kvm
 ```
 После запуска qemu ждёт соединения с gdb-клиентом. Запустим gdb в другом терминале:
 ```
-$ gdb ./build/base/bin/embox
-...
-(gdb) target extended-remote :1234
-(gdb) continue
+    $ gdb ./build/base/bin/embox
+    ...
+    (gdb) target extended-remote :1234
+    (gdb) continue
 ```
 Система начала загружаться.
 
@@ -291,4 +283,3 @@ Embox допускает подключение внешнего репозит
         make ext_conf EXT_PROJECT_PATH=<your projects path>
 ```
 Для того, чтобы темплейты были видны через вызовы `make confload` и `make confload-`, подключеный репозиторий должен иметь структуру папки *project*, а именно *<root_folder>/<project_name>/templates*. Модули могут располагаться в произвольных папках, поиск осуществляется по файлам Mybuild и *.my
-