Разработка шаблона проекта транспайлера¶
Для разработки своего собственного транспайлера вам пригодится разработанный для вас шаблон проекта транспайлера. Скачать и ознакомиться с кодом шаблона вы можете в этом репозитории. Необходимо склонировать этот репозиторий через 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