Skip to content

Latest commit

 

History

History
205 lines (109 loc) · 6.91 KB

README.md

File metadata and controls

205 lines (109 loc) · 6.91 KB
Raw

Edition backend.

This project aims at providing a solution for source code edition, providing services decoupled from any user interface, with an effort of abstraction of the underlying models.

Introduction

Please read the introduction if you never did it and don't know what the project is all about.

Reading the meta-documentation (disclaimer: this is not complete) is:

  • advised before reading documentation
  • mandatory before writing documentation

File system layout

  • project related:
  • sources:
    • doc/: documentation source & content
    • src/: source code of the application
    • test/: tests of the application
  • package related:
    • package.json: npm package.json, the package definition
    • scripts/: scripts to expose various tasks to the developer
    • bin/: public binaries to expose some tasks to the end user
  • others:
    • public/: a web application to demonstrate or test the backend
    • node_modules/: all third-party libraries used by the application

Versioning

To ignore:

  • node_modules/: can be installed from the package.json data with the use of npm

Documentation

As mentioned, the goal is to implement a generic solution to handle source code edition, whatever the language, whatever the UI used behind (i.e. the tool(s)).

If you want to implement a client using this backend, please read this tutorial.

Architecture

You can view an architecture schema by importing the xml file in the doc into the web application draw.io (you can copy the content directly, click on menu item Options>Advanced>Edit...).

We call the tools used to actually edit source code: frontends. They provide the (G)UI.

We call the application serving source edition features (processing): the backend.

A frontend is a client of this backend (therefore acting as a server application), and they communicate through standard means.

Here is a quick description of the stack:

  • backend: a Node.js based application, providing services used by editors and IDEs
  • API: a classical programming interface for the backend, used by the JSON-RPC (Remote Procedure Call protocol using JSON) layer (which is the end point of the communication interface - see below - for the backend)
  • communication interface: JSON-RPC through HTTP (default listening port: 3000)
  • frontend: any IDE or editor with extension capability, using the backend through the communication interface

This project aims at providing everything except the last part: indeed, a frontend is a consumer of the project.

List of known frontends

Ideas for new frontends

  • Sublime Text
  • Notepad++
  • Cloud9
  • a custom/standard frontend (IDE for instance)
  • ... and any other specific tools not even doing edition (but analysis for instance).

Contribute

I would first give an advice to apply everywhere: READ CAREFULLY THE DOCS.

Environment

To be able to develop the project or even use the product you need to:

  • Install Node.js - developed with latest version, tested with version 8, 10 and latest one
    • the node binary must in in the PATH environment variable
  • Install npm (it comes with the installer of Node.js, portable versions are discontinued)

Tested on Microsoft Windows 7 Enterprise 64-bit SP1.

Setup

Install the node modules, by launching from this current directory the command (it might take some time):

npm install

Also, some components inside the package need to be generated, so run from anywhere the command:

npm run build

Try

Test

You can also run the set of tests, and you MUST DO IT when you develop, before requesting any integration of your work.

For that, simply run the npm script:

npm test

Development utilities

To avoid rebuilding the grammars manually anytime you change them, or any other file that needs to be rebuilt, you can use the provided watch script. Run it from the root of the package, like this:

npm run watch

However, for now it doesn't handle restarting the whole application (the server) when a change is made in its code, because this is a bit heavy and requires some subtle logic to keep it handy.

But you can use the native npm script to restart the application:

npm restart

This is possible due to the fact that a stop script has been added in addition to the start one. So you can also do:

npm stop

to shut the server down, instead of manually sending a kill signal.

Development

All folders inside this project have a main documentation file like this one, where they describe everything needed to understand it, and to contribute to it. So please refer to them.

Sub-sections below discuss about development at the whole project scale.

Package definition

You can update the package by modifying the content of the package.json file.

For that you'll need to know the npm package.json specifications.

What can be done among others:

  • check required modules
    • remove unnecessary modules
    • maybe refine version constraints
  • update the description, tags, etc.

You can also contribute more widely to the packaging of the project by implementing scripts that can be launched by npm and binaries that can be installed by it.

Resources

References

Interesting external libraries: