tools/docs/devs/Enabling-Experimental-Feature.md

   1 # Enabling Experimental Features
   2
   3 This document provides a guide on how to write and build experimental features.
   4
   5 ## What's experimental build?
   6
   7 Experimental build is an executable IoT.js including features that are not yet ready for wide use, so they are protected by an experimental status. Developers can opt in to enabling these features when building IoT.js, but they should be used with caution. Because the changes in experimental build can include not only a brand new module but also the existing modules stably used. So developers and users may face unexpected side effects. You should be aware that all the features handled in experimental build may change, be broken, or be removed in the future.
   8
   9 ## How to make IoT.js experimental build
  10
  11 You need to make IoT.js using our build script, ["build.py"](https://github.com/Samsung/iotjs/blob/master/tools/build.py), with `--experimental` or `-e` option.
  12
  13  ```bash
  14  tools/build.py --experimental
  15
  16  tools/build.py -e --iotjs-include-module experimental-module
  17
  18  tools/build.py -e --config=build.experimental.config
  19  ```
  20
  21  For selecting modules to be included, you need to notify the script where your modules exist. You can use `--iotjs-include-module` or `--config` option for that. For further information, please refer to [Writing Builtin JavaScript Module](https://github.com/Samsung/iotjs/blob/master/docs/devs/Writing-New-Builtin-Module.md#writing-builtin-javascript-module).
  22
  23 ## Writing Code
  24
  25 ### Identifier for C Code
  26
  27 Once you make IoT.js with `--experimental` option, a symbolic constant named `EXPERIMENTAL` is predefined in compile stage. You can use the identifier to seperate your experimental code from others as follows.
  28
  29 ```c
  30 #ifdef EXPERIMENTAL
  31   // experimental
  32 #else
  33   // normal
  34 #endif
  35
  36 #ifndef EXPERIMENTAL
  37   // normal
  38 #else
  39   // experimental
  40 #endif
  41 ```
  42
  43 ### Identifier for JavaScript Code
  44
  45 In the case of javascript code, you can refer to `process.env.IOTJS_ENV` to check if running IoT.js is built with experimental features.
  46
  47 ```javascript
  48 if (process.env.IOTJS_ENV === 'experimental') {
  49   // experimental
  50 } else {
  51   // normal
  52 }
  53 ```
  54
  55 ## Documentation
  56
  57 When documenting a guide or an API reference about your experimental module, it's required to explicitly indicate that the features are experimental. Please put the same caution below in every single document.
  58
  59 > :exclamation: This document describes an experimental feature and considerations. Please be aware that every experimental feature may change, be broken, or be removed in the future without any notice.