Разработка шаблона проекта транспайлера¶

Для разработки своего собственного транспайлера вам пригодится разработанный для вас шаблон проекта транспайлера. Скачать и ознакомиться с кодом шаблона вы можете в этом репозитории. Необходимо склонировать этот репозиторий через git. Как пользоваться Git репозиторием написано в Основы Git и Управление репозиториями. В данных статьях вы ознакомитесь с тем, как установить и пользоваться Git, как настроить свой доступ и свой репозиторий на сайте. Кроме того, ниже представлена пошаговая инструкция, как сделать копию репозитория шаблона транспайлера. Обращаю внимание, что в данных статьях можно пробовать все команды, кроме git push. Эту команду можно использовать только тогда, когда вы понимаете, что она делает. Если кратко, то эта команда заливает ваш код в удаленный репозиторий. Если сделать что-то не так, то можно испортить удаленный репозиторий. В данном руководстве мы будем пользоваться git push, т.к. эта команда нам необходима для создания копии шаблона транспайлера в свой репозиторий своего проекта.

Как сделать свой проект на основе шаблона транспайлера через Git¶

Инструкция ниже предполагает, что вы установили Git (Установка Git). Кроме того, при установке Git у вас установится удобный терминал Git Bash, в котором вы будете выполнять описанные ниже команды.

Сначала необходимо создать свой проект на сайте. Об этом вы прочитали здесь. Далее на своем компьютере создаем и переходим в папку со своими проектами. Запускаем на нашей папке Git Bash:

Далее в открывшемся терминале клонируем проект trans_browser (знак $ копировать не надо - это просто обозначение команд терминала):

$ git clone http://test@civnote.ru/trans_browser.git
$ cd trans_browser

Также не забываем, что для работы с Git, вам необходимо его немного настроить, а именно указать свои контактные данные. Именно эти контакты будут отображаться в истории проекта, чтобы указать авторство тех или иных изменений в проекте:

$ git config --global user.name "Your name" 
$ git config --global user.email your@email.com

Затем необходимо удалить текущий удаленный репозиторий (trans_browser), добавить репозиторий от своего проекта (который вы создали ранее на сайте) и последней командой просмотрим новый удаленный репозиторий. Вместо ssh://git@civnote.ru/name_of_your_repo.git вам надо будет подставить ссылку на свой репозиторий (как настроить доступ в репозиторий и найти на него ссылку читаем здесь - раздел "Настройка ключей доступа к репозиторию").

$ git remote rm origin
$ git remote add origin ssh://git@civnote.ru/name_of_your_repo.git
$ git remote show origin

В результате должен отобразиться репозиторий вашего проекта, а не репозиторий http://test@civnote.ru/trans_browser.git

Далее необходимо получить изменения из своего репозитория, чтобы объединить их с проектом trans_browser:

$ git fetch origin

Объединяем код проекта trans_browser и нашего проекта:

$ git merge origin/master --allow-unrelated-histories

Просмотрим состояние репозитория и убедимся, что скорее всего слияние веток произошло с конфликтами:

$ git status

Чтобы удалить конфликты необходимо отредактировать файл README.md в рабочей директории проекта на своем компьютере и убрать из него конструкции обработки конфликтов Git. Проще всего это можно сделать с помощью редактора Visual Studio Code (далее Code). Открываем папку проекта в Code. В терминале можно запустить Code для текущей директории (это нам как раз и нужно):

$ code .

При открытии файла README.md редактор Code предложит выбрать один из вариантов обработки конфликта (выбираем "Принять текущие изменения):

Иначе можно отредактировать файл вручную и удалить конструкции, которые добавил Git. Это первая и три последних строки в файле README.md.

Далее необходимо добавить все файлы в индекс, сделать коммит и залить итоговый код в свой репозиторий:

$ git add .
$ git commit -m "Merge ended" 

Перед заливкой кода в репозиторий еще раз необходимо убедиться, что в настройках удаленного репозитория указан именно ваш репозиторий вашего проекта:

$ git remote show origin

Если адрес репозитория верен, то с чистой совестью заливаем код в свой проект на сайте:

$ git push origin master

Об успехе заливки можно убедиться на странице хранилища своего проекта.

Установка зависимостей шаблона и запуск задач сборки всего проекта¶

После создания копии проекта транспайлера необходимо убедиться, что у вас стоит node.js (выполняем в терминале):

$ node -v

Эта команда должна вывести версию Node.js. Если выводит сообщение, что node системе неизвестен, то качаем Node.js. Вместе с Node у вас должен установиться пакетный менеджер npm. Открываем папку проекта в Visual Studio Code, если не сделали этого ранее.

Также необходимо открыть корень проекта в терминале. Если ранее выше по инструкции вы открыли проект в Git Bash, то открывать проект заново в терминале уже не надо. Запустить терминал можно через проводник Windows или команду на папке Git Bash here, либо открыть встроенный в Code терминал. Делается это сочетанием клавиш Ctrl+`. При запуске терминала Code может предложить настроить оболочку терминала. Советую выбирать либо Power Shell, либо Git Bash. Они гораздо удобнее и дают подсветку вывода.

В терминале вбиваем:

$ npm install

Это установит все зависимости проекта, которые указаны в файле package.json. Необходимо будет немного подождать, т.к. зависимостей очень много и время установки сильно зависит от скорости интернета и общей тормознутости вашего компьютера. Все зависимости установятся в директорию node_modules в корень нашего проекта. Далее необходимо провести сборку проекта следующей командой:

$ npm run gulp

Если при запуске происходит ошибка, то, возможно, поможет установка gulp-cli глобально. Эта утилита будет при вызове в консоли команды gulp искать сам gulp установленный локально в текущей директории. Т.е. gulp-cli это чисто консольная утилита, задача которой запускать gulp, установленный в вашем проекте. Кстати, gulp есть в зависимостях проекта в файле package.json. После ранее запущенной команды $ npm install, gulp должен был установлен локально для нашего проекта в папке node_modules. Глобально ставить сам gulp не рекомендуется:

$ npm install --global gulpjs/gulp-cli

Или просто:

$ npm install --global gulp-cli

И тогда в корне проекта можно просто запускать:

$ gulp

Если что-то пошло не так, то можно попробовать старый вариант запуска $ npm run gulp. При успешном запуске в терминале должно вывестись большое количество сообщений, которые говорят о запуске тех или иных задач. Также в терминал будут выводиться сообщения сервера. Сервер будет отдавать файлы из папки public в браузер пользователя. Нормальный вывод выглядит примерно так:

После запуска Gulp, должен автоматически запуститься браузер, в котором отобразится пример страницы. В консоли разработчика Chrome (F12 -> Console) вы можете заметить вывод нашего транспайлера. Теперь при любом изменении файлов в директории app автоматически будет перезапускаться сборка проекта в папку public, а также будет производиться обновление страницы в браузере. Теперь вам нет необходимости после каждого изменения обновлять страницу в браузере! Но это будет работать только при запущенном gulp. Как только вы его остановите, то перестанут работать и обновления, и сервер.

В проекте во многих файлах я написал большое количество комментариев. Очевидно, что для чтения кода они могут мешать в силу их большого количества. Для очистки кода от комментариев используется следующая команда:

$ gulp strip или $ npm run gulp strip

Эта команда сделает копию проекта в папку nocomments и удалит там во всех файлах комментарии. Можете не переживать, жизненно необходимые комментарии кода из оригинального проекта никуда не пропадут.

Обзор кода и где писать код транспайлера¶

Стоит обратить внимание, что в проекте используется сборка файлов транспайлера в один минимизированный файл transpiler.min.js. При минимизации удаляются все пробельные символы и переименовываются переменные в более короткие. Благодаря sourcemaps, которые добавлены комментарием в transpiler.min.js, мы можем проводить трассировку кода по оригинальным файлам транспайлера, хотя в браузере запускается только transpiler.min.js (это можно понять, если глянуть на index.html). Посмотреть полученные исходники, как и минимизированный файл можно в консоли разработчика Chrome (F12 -> Sources):

Можете ставить брэйкпоинты прямо на lexer.js или transpiler.core.js, хотя очевидно, что браузер интерпретирует не их, а transpiler.min.js!

transpiler.min.js выглядит так:

Можно даже оценить минимизированный код после улучшения отображения, а также результат работы Sourcemaps:

Обращаю внимание, что почти весь свой код вы будете писать в директории app/transpile_components. Эта папка содержит в себе компоненты транспайлера, которые будут затем собираться в единый файл транспайлера transpiler.min.js. Для первой лабы вам необходимо дописать код лексического анализатора в файл app/transpile_components/lexer.js. По сути от вас требуется только вставить код со своим алгоритмом. Кроме того, вам необходимо сделать таблицу лексем для своего входного языка. В шаблоне таблица находится в папке app/assets/config/lex_table.json. Необходимо этот файл заменить на свой. Также надо обновить файл app/assets/index.html - необходимо указать свои типы скриптов. Типы скриптов указываются в атрибуте type и в него записывается MIME-тип ресурса. В MIME-тип рекомендуется использовать только маленькие буквы. Т.е. такие теги:

<script type="text/typescript" src="./typescript/test.ts"></script>

Необходимо заменить на (меняем MIME-тип, название директории с входным кодом и расширение файлов с кодом на входном языке):

<script type="text/yourlanguagename" src="./yourlanguagename/test.xxx"></script>

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

Структура проекта¶

.
├── app - исходные коды транспайлера
│   ├── assets - статичные файлы для примера (HTML, JS, CSS, которые описывают страничку для пользователя). Здесь вам необходимо отредактировать index.html и lex_table.json
│   └── transpile_components - файлы транспайлера. Именно здесь вы должны писать свой исходный код для транспайлера. Все остальные файлы проекта служат для настройки.
├── public - собранные Gulp файлы, которые будет отдавать сервер в браузер пользователя
├── nocomments - файлы проекта с вырезанными комментариями
├── node_modules - внешние зависимости нашего проекта (устанавливаются через npm install)
├── gulpfile.js - запускает через Gulp задачи по сборке проекта.
├── package.json - информация о проекте и его зависимостях
├── README.md - документация по проекту
├── server.js - сервер, который отдает файлы из папки public пользователю в браузер
└── .gitignore - файлы, которые должен пропускать Git