Developer documentation

What can I do developing for asterism ?

🚧 TODO (possibilities, req skills)

Quick install guide

Unlike for end user, the developer won't use asterism-for-domotics project. You will need to install asterism core project, and use a copy of asterism-plugin-template. You need to follow these steps:

• Copy or fork asterism-plugin-template repository to obtain your own plugin repository. Please rename your project, choose the name you want, but a name like 'asterism-plugin-...' is recommended for easy referencing on npmjs/github. Please use a consistent repository name (like github and npmjs need).

• Install asterism source code NEXT TO your plugin repository (in the same dir, it's important), with git for example:

git clone https://www.github.com/gxapplications/asterism

• Go inside asterism directory and install dependencies:

cd asterism
npm install
HOST=<your host name> npm run gen:cert

This can take a while and a lot of space...

• Go inside your <asterism-plugin-...> project and install dependencies:

cd ../<asterism-plugin-...>
npm install

A warning should tells you that the asterism PEER DEPENDENCY is missing: forget it, we don't need it.

• Rename your project in the manifest file (lib/index.js) and in the package.json file. You can search & replace for word 'asterism-plugin-template' and use your repository name <asterism-plugin-...>.

• Now you must link your <asterism-plugin-...> projet as a dependency in asterism. The classical 'npm link' cannot work properly in our case, so I made a script to link properly your project:

npm run wrap

Maybe sudo permissions are needed, it's up to you to fix perms before or to you root perms. This needs to be tested under Windows platforms...

• From your <asterism-plugin-...> directory, you can test and launch asterism with your new dependency:

npm run start

Run it from <asterism-plugin-...>, not from asterism! The start script will in fact launch asterism project with specific parameters to include your project as plugin.

Start looking for an example

Now you have a working application, reachable from http://localhost:8090 by default. The source of asterism-plugin-template contains many examples, so you can test them on the interface.

Look after the JSDoc below to understand main entities that should be provided through your plugin.

API

A JSDoc is available for common classes/utilities

Recommendations

Even though the started server is a nodemon watching for changes in the files, some modifications will be hot-reloaded in the interface, but there is some files that cannot be hot-reloaded:

• some first level files (lib/index.js, lib/item-factory.jsx, lib/settings.jsx) need a server restart after each modification. These are the first files you will need to modify, but once your plugin is well declared, you should not change them very often.
• each change to lib/index.js (manifest) induce the need to run again 'npm dist' and to restart server.

🚧 TODO (do and do not)

How to join to the list of contributors

🚧 TODO