README
¶
Serulian Toolkit - Toolkit and Compiler for building Serulian projects
The Serulian toolkit and compiler provides tooling for developing, building, formatting and testing Serulian web/mobile applications.
Project Status
The Serulian toolkit is currently in alpha level development, which means it will be changing rapidly without guarentees of backwards compatibility. The toolkit itself is however fairly advanced in implementing the spec and various tooling, with significant testing of the compilation system already in place.
Commands
Building a project
To build a project, execute build with the entrypoint Serulian source file for that project:
./serulian build entrypointfile.seru
The project will be built and output as entrypointfile.seru.js and entrypointfile.seru.js.map in the current directory.
Developing a project
To use the Serulian toolkit in an edit-refresh-compile development mode, run the develop command with the entrypoint Serulian source file for that project:
./serulian develop entrypointfile.seru
The toolkit will then start a webserver on the desired port (default 8080):
Serving development server for project entrypointfile.seru on :8080 at /entrypointfile.seru.js
Add the following <script> tag to your application:
<script type="text/javascript" src="http://localhost:8080/entrypointfile.seru.js"></script>
On page load (or refresh) the project will be recompiled, with compilation status and any errors or warnings displayed in the web console.
Formatting source code
The Serulian toolkit command format can be used to reformat Serulian source code:
./serulian format somedir/...
The above will reformat all Serulian files found under the somedir directory.
Working with imports
Imports in Serulian are usually tied to a specific commit SHA or tagged version. The Serulian toolkit commands freeze, unfreeze, update and upgrade can be used to easily manage the versions of these imports.
Freeze
The imports freeze command can be used to rewrite the import to point to its current HEAD SHA:
./serulian imports freeze ./... github.com/serulian/somelib
Contents of the matching source file after freeze:
from "github.com/serulian/somelib:somesha" import SomeThing
Unfreeze
The unfreeze command can be used to rewrite imports back to HEAD, for real-time development:
./serulian imports unfreeze ./... github.com/serulian/somelib
Update
If the library being imported is versioned using Semantic Versioning, the additional command update can be used to update the import from an existing semantic version to a minor later version:
Given contents:
from "github.com/serulian/somelib@v1.2.3" import SomeThing
Running:
./serulian imports update ./... github.com/serulian/somelib
Contents of the matching source file after update:
from "github.com/serulian/somelib@v1.3.0" import SomeThing
Note: The version will not be upgraded if the only change available is a major version change. To apply a major version change, use upgrade.
Upgrade
If the library being imported is versioned using Semantic Versioning, the additional command upgrade can be used to upgrade the import to the latest stable version:
./serulian imports upgrade ./... github.com/serulian/somelib
Contents of the matching source file after upgrade:
from "github.com/serulian/somelib@v1.2.3" import SomeThing
Testing a project
The Serulian toolkit can use one or more test runners to test Serulian projects. The current default runner is the Karma test runner with the Jasmine.
Writing tests
Note: The following is subject to change in the near future.
Tests are Serulian source files ended with the suffix _test.seru. For example, a file foo.seru would have an associated test file named foo_test.seru.
All test files must have an entrypoint function named TEST that describes the various tests (using Jasmine test format) to be run. Note that all tests must be asynchronous (i.e. call the done() method when complete).
// Import the various Jasmine definitions. A jasmine.webidl defining these functions is required.
from webidl`jasmine` import describe
from webidl`jasmine` import it
from webidl`jasmine` import expect
/**
* TEST defines the entrypoint function for describing all the tests.
*/
function<void> TEST() {
// Describe a single test group.
describe('Bool', function() {
// Describe a single test.
describe('equal', function() {
// Add a requirement to be tested.
it(&'true should be equal to true', function(done function<void>()) {
expect(true).toBe(true);
// Mark the test's body as complete.
done()
})
})
})
}
Running tests
To run tests, execute the test command with the proper runner and entrypoint:
./serulian test karma ./...
The test runner plugin (in this case Karma) will ensure the necessary packages are installed and then run the specified tests.
Running via container
A pre-built container image is always available. For example, the following with build a project via Docker. Note the mounting of the directory containing the project.
docker pull quay.io/serulian/compiler:latest
docker run -t -v /my/source/path:/project quay.io/serulian/compiler:latest build project/myfile.seru
Directories
¶
| Path | Synopsis |
|---|---|
|
builder package defines the library for invoking the full compilation of Serulian code.
|
builder package defines the library for invoking the full compilation of Serulian code. |
|
Package bundle defines interfaces for bundling together the files produced by a run of a generator.
|
Package bundle defines interfaces for bundling together the files produced by a run of a generator. |
|
cmd
|
|
|
serulian
package main is the serulian compiler.
|
package main is the serulian compiler. |
|
Package compilercommon defines common types and their functions shared across the compiler.
|
Package compilercommon defines common types and their functions shared across the compiler. |
|
Package compilergraph defines methods for loading and populating the overall Serulian graph.
|
Package compilergraph defines methods for loading and populating the overall Serulian graph. |
|
compilerutil package defines utility methods.
|
compilerutil package defines utility methods. |
|
developer package defines a webserver for serving compiled code that automatically re-compiles on refresh.
|
developer package defines a webserver for serving compiled code that automatically re-compiles on refresh. |
|
formatter package defines a library for formatting Serulian source code.
|
formatter package defines a library for formatting Serulian source code. |
|
generator
|
|
|
es5
The es5 package implements a generator for compiling Serulian into ECMAScript 5.
|
The es5 package implements a generator for compiling Serulian into ECMAScript 5. |
|
es5/codedom
codedom package contains types representing a lower-level IR for easier construction of ES5.
|
codedom package contains types representing a lower-level IR for easier construction of ES5. |
|
es5/dombuilder
dombuilder package defines methods for translating the Serulian SRG into the codedom IR.
|
dombuilder package defines methods for translating the Serulian SRG into the codedom IR. |
|
es5/expressiongenerator
expressiongenerator defines code for translating from CodeDOM expressions into esbuilder ExpressionBuilder objects.
|
expressiongenerator defines code for translating from CodeDOM expressions into esbuilder ExpressionBuilder objects. |
|
es5/statemachine
statemachine package contains the helper code for generating a state machine representing the statement and expression level of the ES5 generator.
|
statemachine package contains the helper code for generating a state machine representing the statement and expression level of the ES5 generator. |
|
escommon
escommon defines common packages and methods for generating ECMAScript.
|
escommon defines common packages and methods for generating ECMAScript. |
|
escommon/esbuilder
The esbuilder package implements an ECMAScript AST for easier generation of code with source mapping references.
|
The esbuilder package implements an ECMAScript AST for easier generation of code with source mapping references. |
|
This is a *generic* implementation of a lexer.
|
This is a *generic* implementation of a lexer. |
|
graphs
|
|
|
scopegraph
Package scopegraph defines methods for creating and interacting with the Scope Information Graph, which represents the determing scopes of all expressions and statements.
|
Package scopegraph defines methods for creating and interacting with the Scope Information Graph, which represents the determing scopes of all expressions and statements. |
|
scopegraph/proto
Package proto is a generated protocol buffer package.
|
Package proto is a generated protocol buffer package. |
|
srg
srg package defines methods for interacting with the Source Representation Graph.
|
srg package defines methods for interacting with the Source Representation Graph. |
|
typegraph
typegraph package defines methods for creating and interacting with the Type Graph, which represents the definitions of all types (classes, interfaces, etc) in the Serulian type system defined by the parsed SRG.
|
typegraph package defines methods for creating and interacting with the Type Graph, which represents the definitions of all types (classes, interfaces, etc) in the Serulian type system defined by the parsed SRG. |
|
typegraph/proto
Package proto is a generated protocol buffer package.
|
Package proto is a generated protocol buffer package. |
|
Package grok provides helpers and tooling for reading, understanding and writing Serulian code.
|
Package grok provides helpers and tooling for reading, understanding and writing Serulian code. |
|
Package integration defines interfaces and helpers for writing integrations with Serulian.
|
Package integration defines interfaces and helpers for writing integrations with Serulian. |
|
Package packageloader defines functions and types for loading and parsing source from disk or VCS.
|
Package packageloader defines functions and types for loading and parsing source from disk or VCS. |
|
Package packagetools implements tools for working on Serulian packages.
|
Package packagetools implements tools for working on Serulian packages. |
|
Package parser defines the full Serulian language parser and lexer for translating Serulian source code into an abstract syntax tree (AST).
|
Package parser defines the full Serulian language parser and lexer for translating Serulian source code into an abstract syntax tree (AST). |
|
shared
Package shared defines types shared by all parser implementations.
|
Package shared defines types shared by all parser implementations. |
|
v0
Package parser defines the full Serulian language parser and lexer for translating Serulian source code into an abstract syntax tree (AST).
|
Package parser defines the full Serulian language parser and lexer for translating Serulian source code into an abstract syntax tree (AST). |
|
v1
Package parser defines the full Serulian language parser and lexer for translating Serulian source code into an abstract syntax tree (AST).
|
Package parser defines the full Serulian language parser and lexer for translating Serulian source code into an abstract syntax tree (AST). |
|
sourcemap is a package which defines types and methods for working with V3 of the SourceMap spec: https://goo.gl/Bn7iTo
|
sourcemap is a package which defines types and methods for working with V3 of the SourceMap spec: https://goo.gl/Bn7iTo |
|
Package sourceshape defines the types representing the structure of source code.
|
Package sourceshape defines the types representing the structure of source code. |
|
package tester implements support for testing Serulian code.
|
package tester implements support for testing Serulian code. |
|
karma
package karma implements support for testing Serulian code via the karma testing framework.
|
package karma implements support for testing Serulian code via the karma testing framework. |
|
vcs package defines helpers functions and interfaces for working with Version Control Systems such as git, including discovery of VCS information based on the Golang VCS discovery protocol.
|
vcs package defines helpers functions and interfaces for working with Version Control Systems such as git, including discovery of VCS information based on the Golang VCS discovery protocol. |
|
Package version defines the versioning information for the toolkit.
|
Package version defines the versioning information for the toolkit. |
|
Package webidl defines the WebIDL integration for Serulian.
|
Package webidl defines the WebIDL integration for Serulian. |
|
graph
Package graph defines the graph for the WebIDL integration.
|
Package graph defines the graph for the WebIDL integration. |
|
parser
This is a *generic* implementation of a lexer.
|
This is a *generic* implementation of a lexer. |