Improve readme (eclipse-thingweb#1114)

* docs(README): move license as last section * docs(readme): improve overall description * docs(README): add logo * docs(REDME): use github alerts syntax Co-authored-by: Jan Romann <[email protected]> * docs(README): improve examples introduction Co-authored-by: Jan Romann <[email protected]> * docs(README): minor typos Co-authored-by: Jan Romann <[email protected]> * docs(README): fix small typo Co-authored-by: Jan Romann <[email protected]> * docs(REAMDE): fix typos Co-authored-by: Ege Korkan <[email protected]> * docs(REAMDE): use information model instead of metamodel Co-authored-by: Ege Korkan <[email protected]> * docs(README): fix eg. * docs(README): use uppercase title Co-authored-by: danielpeintner <[email protected]> * docs(README): fix width attribute in the logo Co-authored-by: danielpeintner <[email protected]> * Move "development internals" to bottom * Fix linting issue * Update CONTRIBUTING.md Co-authored-by: Cristiano Aguzzi <[email protected]> --------- Co-authored-by: Jan Romann <[email protected]> Co-authored-by: Ege Korkan <[email protected]> Co-authored-by: danielpeintner <[email protected]>
danielpeintner · Oct 13, 2023 · b44448b · b44448b
1 parent b8aeef6
commit b44448b
Show file tree

Hide file tree

Showing 2 changed files with 259 additions and 236 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -33,6 +33,88 @@ Thus, before your contribution can be accepted by the project team, contributors
 For more information, please see the Eclipse Committer Handbook:
 https://www.eclipse.org/projects/handbook/#resources-commit
 
+## Clone and build
+
+Clone the repository:
+
+```
+git clone https://github.com/eclipse-thingweb/node-wot
+```
+
+Go into the repository:
+
+```
+cd node-wot
+```
+
+Install root dependencies (locally installs tools such as [typescript](https://www.npmjs.com/package/typescript)):
+
+```
+npm ci
+```
+
+Use `tsc` to transcompile TS code to JS in the `dist` directory for each package:
+_Note: This step automatically calls `npm run bootstrap`._
+
+```
+npm run build
+```
+
+#### Optional steps
+
+###### Link Packages
+
+Make all packages available on your local machine (as symlinks). You can then use each package in its local version via `npm link <module>` instead of `npm install <module>` (see also https://docs.npmjs.com/cli/link). This is also useful if you want to test the CLI with a local script.
+
+```
+sudo npm run link
+```
+
+(On Windows omit `sudo`)
+
+##### Link Local wot-typescript-definitions
+
+When experimenting with new APIs, developers might need to change the [wot-typescript-definitions](https://www.npmjs.com/package/wot-typescript-definitions). If you want to use your own version of wot-types-defitions you can link your local copy using the following steps.
+Use npm link for this as well:
+
+```
+git clone https://github.com/w3c/wot-scripting-api/
+cd wot-scripting-api/typescript/
+sudo npm link
+```
+
+(On Windows omit `sudo`)
+
+In each node-wot package, link the local version made available in the previous step:
+
+```
+sudo npm link wot-typescript-definitions
+```
+
+(On Windows omit `sudo`)
+
+##### Optimization
+
+To reduce the size of the installation from about 800 MByte down to about 200 MByte, you can run the following commands (currently only tested on Linux):
+`npm prune --production`
+
+#### Troubleshooting
+
+-   Build error about `No matching version found for @node-wot/...` or something about `match`
+    -   try `npm run unlock` from the project root before building
+-   `sudo npm run link` does not work
+    -   try `npm run unlock` from the project root before calling `[sudo] npm run link`
+    -   try `npm link` in each package directory in this order: td-tools, core, binding-\*, cli, demo-servients
+-   Error mesage for `npm link @node-wot/<module>`
+    `ELOOP: too many symbolic links encountered, stat '/usr/lib/node_modules/@node-wot/<module>`
+    1. Run `npm run link` in `thingweb.node-wot` again
+    2. Remove `node_modules` in the targeted project
+    3. Remove all `@node-wot/<module>` dependencies in your `package.json`
+    4. Run `npm i` again
+    5. Install the packages with `npm link @node-wot/<module>`
+-   Build error around `prebuild: npm run bootstrap`
+    -   This has been seen failing on WSL. Try using a more recent Node.js version
+
 ## Adding a New Protocol Binding
 
 In order to add support for a new protocol binding, you need to implement the protocol interfaces defined in the `core` package.