Skip to content

Commit

Permalink
Replaced Gulp tasks with npm scripts (#440)
Browse files Browse the repository at this point in the history
...so much cleaner!

Fixes #419.
  • Loading branch information
Josh Goldberg committed Aug 16, 2018
1 parent 119a81b commit cbda1c1
Show file tree
Hide file tree
Showing 13 changed files with 649 additions and 6,033 deletions.
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,13 @@ lib
node_modules/
npm-debug.log
test/*.js
test/*.js.map
test/**/*.js.map
test/unit/**/*.js
util/*.js
util/*.js.map
util/**/*.js
util/**/*.js.map

# TS-GLS testing will often add these unnecessary files under src/
src/**/*.cs
Expand Down
86 changes: 42 additions & 44 deletions docs/development.md
Original file line number Diff line number Diff line change
@@ -1,61 +1,34 @@
# Development

GLS uses [Gulp](http://gulpjs.com/) to automate building, which requires [Node.js](http://node.js.org).
To build from scratch, install [Node.js](http://node.js.org) and run `npm install` to install development dependencies.
GLS is written in [TypeScript](http://typescriptlang.org).

To build from scratch, install Node.js and run the following commands:

```
npm install -g gulp
npm install
gulp
```
The recommended setup is [Visual Studio Code](https://code.visualstudio.com) with the [TSLint extension](https://marketplace.visualstudio.com/items?itemName=eg2.tslint).

To build, run `gulp`.
You can build+lint the souce without running tests using `gulp src`, or just build+lint+run tests using `gulp test`.
The full list of tasks is in `gulpfile.js`.
To run a full build+lint+test, run `npm run verify`.

Alternately, use `tsc` to build source files under `/src` to `/lib`, and `tsc -w` to build upon file changes.
This is faster but doesn't run linting.
Use `npm run watch` to run the TypeScript compiler in watch mode on both source and test files.

Alternately, you can build+lint individual sections of code:

## Coding for GLS
* `npm run src`: GLS source code.
* `npm run test`: Test file infrastructure.
* `npm run util`: Miscellaneous utilities.

The recommended setup is [Visual Studio Code](https://code.visualstudio.com) with the [TSLint extension](https://marketplace.visualstudio.com/items?itemName=eg2.tslint).
The full list of tasks is in `package.json`.

### Style Guidelines
## Style Guidelines

Most rules are enforced by [TSLint](https://palantir.github.io/tslint).
For those that aren't, follow the existing conventions, including sensible variable names, consistent indentation, and correct grammar, spelling, and punctuation.

### Adding Commands

Command class instances are stored at runtime by their unique string name.
When adding a new command under `src/Commands`, also add a line for it under `src/CommandsBagFactory`.

When adding a new command class, you'll need to override the abstract `getMetadata` and `render` commands.

To directly see which files you should add or edit to add a new command, run a full-text search on both the PascalCase command name (e.g. `MemberFunction`) and the GLS style name (e.g. `member function`).

_([#375](https://github.com/general-language-syntax/GLS/issues/375) tracks adding a utility to automate adding this!)_

#### "Native" Commands

Some commands, such as native math operations, directly call into native APIs and would require a lot of repeated source code to represent.
A `NativeCallCommand` sub-class of `Command` can be extended from for these.
It requires overriding the abstract `retrieveNativeCallProperties` instead of `render`, which returns the language's `NativeCallProperties` for that command.

### Adding Languages

Languages are stored at runtime by their language name in a `LanguagesBag`.
You can add a new language by running `gulp util:new-language --language-name <language-name> --language-extension <language-extension> --base-name <base-name> --base-extension <base-extension>`.

Files and listings for a new language identical to the original language except for the name and extension will be added locally.
## Tests

### Unit Tests

These are stored under `test/unit/**/*.ts` and compiled to equivalent files under `test/unit/**/*.js`.

You can run them with `gulp test:unit`, or directly with the `mocha` CLI.
You can run them with `npm run test:unit`, or directly with the `mocha` CLI.
Use `mocha` to specify tests:

```shell
Expand All @@ -67,15 +40,40 @@ mocha test/unit/Tokenization/Parsers/SourceLineParser.js -g "nested CommandNode"

Test for compiled GLS output are located under [test/integration](https://github.com/general-language-syntax/GLS/tree/master/test/integration) and [test/end-to-end](https://github.com/general-language-syntax/GLS/tree/master/test/end-to-end).
Tests are represented by a folder of files, where one file is GLS source code and each other file is how that code should look when compiled to each other language.
You can run specific suites of tests using `gulp test:integration` or `gulp test:end-to-end`.
You can run specific suites of tests using `npm run test:integration` or `npm run test:end-to-end`.

You can run a subset of commands by passing `--command`:
You can run a subset of commands in either by passing `--command`:

```shell
gulp test:integration --command *string*
gulp test:end-to-end --command StringFormat
npm run test:integration --command *string*
npm run test:end-to-end --command StringFormat
```

When adding a new command, _always_ add new integration tests for it.

When adding a new set of commands around a feature, add an end-to-end test for it.

## Adding Commands

Command class instances are stored at runtime by their unique string name.
When adding a new command under `src/Commands`, also add a line for it under `src/CommandsBagFactory`.

When adding a new command class, you'll need to override the abstract `getMetadata` and `render` commands.

To directly see which files you should add or edit to add a new command, run a full-text search on both the PascalCase command name (e.g. `MemberFunction`) and the GLS style name (e.g. `member function`).

_([#375](https://github.com/general-language-syntax/GLS/issues/375) tracks adding a utility to automate adding this!)_

### "Native" Commands

Some commands, such as native math operations, directly call into native APIs and would require a lot of repeated source code to represent.
A `NativeCallCommand` sub-class of `Command` can be extended from for these.
It requires overriding the abstract `retrieveNativeCallProperties` instead of `render`, which returns the language's `NativeCallProperties` for that command.

## Adding Languages

Languages are stored at runtime by their language name in a `LanguagesBag`.
You can add a new language by running `npm run util:new-language`.
For example: `npm run util:new-language -- --language-name PHP --language-extension .php --base-name Ruby --base-extension .rb`.

Files and listings for a new language identical to the original language except for the name and extension will be added locally.
Loading

0 comments on commit cbda1c1

Please sign in to comment.