Add initial version of documentation to source tree.

JerryScript-DCO-1.0-Signed-off-by: Evgeny Gavrin e.gavrin@samsung.com

README.md

@@ -1,8 +1,35 @@
-## JerryScript
-
-You can find project details in [wiki](http://samsung.github.io/jerryscript/ "Jerry Script") and [project page](http://www.jerryscript.net)
-
-Join the conversation.
+# JerryScript: JavaScript engine for Internet of Things
 [![Join the chat at https://gitter.im/Samsung/jerryscript](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Samsung/jerryscript?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![License](https://img.shields.io/badge/licence-Apache%202.0-brightgreen.svg?style=flat)](LICENSE)
 
 
+JerryScript is the lightweight JavaScript engine for very constrained devices such as microcontrollers:
+- Only few kilobytes of RAM available to the engine (<64 KB RAM)
+- Constrained ROM space for the code of the engine (<200 KB ROM)
+
+Additional informantion can be found on our [project page](http://samsung.github.io/jerryscript/) and  [wiki](https://github.com/Samsung/jerryscript/wiki).
+
+## Quick Start
+### Getting Sources
+```bash
+git clone https://github.com/Samsung/jerryscript.git jr
+cd jr
+```
+
+### Building
+```bash
+make release.linux -j
+```
+
+For Additional information see [Development](docs/DEVELOPMENT.md).
+
+## Documentation
+- [API Reference](docs/API-REFERENCE.md)
+- [API Example](docs/API-EXAMPLE.md)
+
+## License
+JerryScript is Open Source software under the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0). Complete license and copyright information can be found within the code.
+
+> Copyright 2015 Samsung Electronics Co., Ltd.
+
+> Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

docs/API-EXAMPLE.md

@@ -0,0 +1,298 @@
+JerryScript Engine can be embedded into any application, providing the way to run JavaScript in a large range of environments - from desktops to low-memory microcontrollers.
+
+This guide is intended to introduce you to JerryScript embedding API through creation of simple JavaScript shell.
+
+## Step 1. Execute JavaScript from your application
+
+```cpp
+#include <string.h>
+#include "jerry.h"
+
+int
+main (int argc, char * argv[]) {
+  char script [] = "print ('Hello, World!');";
+
+  jerry_completion_code_t code = jerry_run_simple (script,
+                                                   strlen (script),
+                                                   JERRY_FLAG_EMPTY);
+}
+```
+
+The application will generate the following output:
+
+```bash
+Hello, World!
+```
+
+## Step 2. Split engine initialization and script execution
+
+Here we perform the same actions, as `jerry_run_simple`, while splitting into several steps:
+
+- engine initialization
+- script code setup
+- script execution
+- engine cleanup
+
+
+```cpp
+#include <string.h>
+#include "jerry.h"
+
+int
+main (int argc, char * argv[]) {
+  char script [] = "print ('Hello, World!');";
+
+  // Initialize engine
+  jerry_init (JERRY_FLAG_EMPTY);
+
+  // Setup Global scope code
+  jerry_parse (script, strlen (script));
+
+  // Execute Global scope code
+  jerry_completion_code_t code = jerry_run ();
+
+  // Cleanup engine
+  jerry_cleanup ();
+}
+```
+
+Our code is more complex now, but it introduces possibilities to interact with JerryScript step-by-step: setup native objects, call JavaScript functions, etc.
+
+## Step 3. Execution in 'eval'-mode
+
+```cpp
+#include <string.h>
+#include "jerry.h"
+
+int
+main (int argc, char * argv[]) {
+  char script1 [] = "var s = 'Hello, World!';";
+  char script2 [] = "print (s);";
+
+  // Initialize engine
+  jerry_init (JERRY_FLAG_EMPTY);
+
+  jerry_api_value_t eval_ret;
+
+  // Evaluate script1
+  jerry_api_eval (script1, strlen (script1),
+                  false, false, &eval_ret);
+  // Free JavaScript value, returned by eval
+  jerry_api_release_value (&eval_ret);
+
+  // Evaluate script2
+  jerry_api_eval (script2, strlen (script2),
+                  false, false, &eval_ret);
+  // Free JavaScript value, returned by eval
+  jerry_api_release_value (&eval_ret);
+
+  // Cleanup engine
+  jerry_cleanup ();
+}
+```
+
+This way, we execute two independent script parts in one execution environment. The first part initializes string variable, and the second outputs the variable.
+
+## Step 4. Interaction with JavaScript environment
+
+```cpp
+#include <string.h>
+#include "jerry.h"
+
+int
+main (int argc, char * argv[]) {
+  char str [] = "Hello, World!";
+  char var_name [] = "s";
+  char script [] = "print (s);";
+
+  // Initializing JavaScript environment
+  jerry_init (JERRY_FLAG_EMPTY);
+
+  // Getting pointer to the Global object
+  jerry_api_object_t *obj_p = jerry_api_get_global_object ();
+
+  // Constructing string
+  jerry_api_string_t *str_val_p = jerry_api_create_string (str);
+
+  // Constructing string value descriptor
+  jerry_api_value_t val;
+  val.type = JERRY_API_DATA_TYPE_STRING;
+  val.string_p = str_val_p;
+
+  // Setting the string value to field of the Global object
+  jerry_api_set_object_field_value (obj_p, var_name, &val);
+
+  // Releasing string value, as it is no longer necessary outside of engine
+  jerry_api_release_string (str_val_p);
+
+  // Same for pointer to the Global object
+  jerry_api_release_object (obj_p);
+
+  jerry_api_value_t eval_ret;
+
+  // Now starting script that would output value of just initialized field
+  jerry_api_eval (script, strlen (script),
+                  false, false, &eval_ret);
+  jerry_api_release_value (&eval_ret);
+
+  // Freeing engine
+  jerry_cleanup ();
+}
+```
+
+The sample will also output 'Hello, World!'. However, now it is not just a part of the source script, but the value, dynamically supplied to the engine.
+
+## Step 5. Description of JavaScript value descriptors
+
+Structure, used to put values to or receive values from the engine is the following:
+
+- `type` of the value:
+  - JERRY_API_DATA_TYPE_UNDEFINED (undefined);
+  - JERRY_API_DATA_TYPE_NULL (null);
+  - JERRY_API_DATA_TYPE_BOOLEAN (true / false);
+  - JERRY_API_DATA_TYPE_FLOAT64 (number);
+  - JERRY_API_DATA_TYPE_STRING (string);
+  - JERRY_API_DATA_TYPE_OBJECT (object reference);
+- `v_bool` (if JERRY_API_DATA_TYPE_BOOLEAN) - boolean value;
+- `v_float64` (if JERRY_API_DATA_TYPE_FLOAT64) - number value;
+- `v_string` (if JERRY_API_DATA_TYPE_STRING) - pointer to string;
+- `v_object` (if JERRY_API_DATA_TYPE_OBJECT) - pointer to object.
+
+Abstract values, to be sent to or received from the engine are described with the structure.
+
+Pointers to strings or objects and values should be released just when become unnecessary, using `jerry_api_release_string` or `jerry_api_release_object` and `jerry_api_release_value`, correspondingly.
+
+The following example function will output a JavaScript value:
+
+```cpp
+static void
+print_value (const jerry_api_value_t * value_p)
+{
+  switch (value_p->type)
+  {
+    // Simple values: undefined, null, false, true
+    case JERRY_API_DATA_TYPE_UNDEFINED:
+      printf ("undefined");
+      break;
+    case JERRY_API_DATA_TYPE_NULL:
+      printf ("null");
+      break;
+    case JERRY_API_DATA_TYPE_BOOLEAN:
+      if (value_p->v_bool)
+        printf ("true");
+      else
+        printf ("false");
+      break;
+
+    // Number value
+    case JERRY_API_DATA_TYPE_FLOAT64:
+      printf ("%lf", value_p->v_float64);
+      break;
+
+    // String value
+    case JERRY_API_DATA_TYPE_STRING:
+    {
+      ssize_t neg_req_sz, sz;
+      // determining required buffer size
+      neg_req_sz = jerry_api_string_to_char_buffer (value_p->v_string,
+                                                    NULL,
+                                                    0);
+      assert (neg_req_sz < 0);
+      char * str_buf_p = (char*) malloc (-neg_req_sz);
+      sz = jerry_api_string_to_char_buffer (value_p->v_string,
+                                            str_buf_p,
+                                            -neg_req_sz);
+      assert (sz == -neg_req_sz);
+
+      printf ("%s", str_buf_p);
+
+      free (str_buf_p);
+      break;
+    }
+
+    // Object reference
+    case JERRY_API_DATA_TYPE_OBJECT:
+      printf ("[JS object]");
+      break;
+  }
+
+  printf ("\n");
+}
+```
+
+## Simple JavaScript shell
+
+Now all building blocks, necessary to construct JavaScript shell, are ready.
+
+Shell operation can be described with the following loop:
+
+- read command;
+- if command is 'quit'
+  - exit loop;
+- else
+  - eval (command);
+  - print result of eval;
+  - loop.
+
+```cpp
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "jerry.h"
+
+static void
+print_value (const jerry_api_value_t * value_p);
+
+int
+main (int argc, char * argv[]) {
+  // Initialize engine
+  jerry_init (JERRY_FLAG_EMPTY);
+
+  char cmd [256];
+  while (true) {
+    printf ("> ");
+
+    // Input next command
+    if (fgets (cmd, sizeof (cmd), stdin) == NULL
+        || strcmp (cmd, "quit\n") == 0) {
+      // If the command is 'quit', exit from loop
+      break;
+    }
+
+    jerry_api_value_t ret_val;
+
+    // Evaluate entered command
+    jerry_completion_code_t status = jerry_api_eval (cmd, strlen (cmd),
+                                                     false, false,
+                                                     &ret_val);
+
+    // If command evaluated successfully, print value, returned by eval
+    if (status == JERRY_COMPLETION_CODE_OK) {
+      // 'eval' completed successfully
+      print_value (&ret_val);
+      jerry_api_release_value (&ret_val);
+    } else {
+      // evaluated JS code thrown an exception
+      // and didn't handle it with try-catch-finally
+      printf ("Unhandled JS exception occured\n");
+    }
+
+    printf ("\n");
+    fflush (stdout);
+  }
+
+  // Cleanup engine
+  jerry_cleanup ();
+
+  return 0;
+}
+```
+
+The application inputs commands and evaluates them, one after another.
+
+
+## Further steps
+
+For further API description, please look at [Embedding API](/API).

docs/DEVELOPMENT.md

@@ -0,0 +1,58 @@
+## Development
+### Setting Up Prerequisites
+Currently, only Ubuntu 14.04+ officially supported as primary development environment.
+
+There are several dependencies, that should be installed manually. The following list is required for building:
+- `gcc` or `g++` higher than `4.8.2`
+  - native
+  - arm-none-eabi
+- `cmake` higher than `2.8.12.2`
+- `make` higher than `3.81`
+- `bash` higher than `4.3.11`
+
+```bash
+sudo apt-get install gcc g++ gcc-arm-none-eabi cmake
+```
+
+These tools are required for development:
+- `cppcheck` requires `libpcre`
+- `vera++` requires `tcl`, `tk` and `boost`
+
+```bash
+sudo apt-get install libpcre3 libpcre3-dev
+sudo apt-get install tcl8.6 tcl8.6-dev tk8.6-dev libboost-all-dev
+```
+
+Upon first build, `make` would try to setup prerequisites, required for further development and pre-commit testing:
+- STM32F3 and STM32F4 libraries
+- cppcheck 1.66
+- vera++ 1.2.1
+
+```bash
+make prerequisites -j
+```
+It may take time, so go grab some coffee:
+
+```bash
+Setting up prerequisites... (log file: ./build/prerequisites/prerequisites.log)
+```
+
+### Building Debug Version
+To build debug version for Linux:
+```bash
+make debug.linux -j
+```
+
+To build debug version for Linux without LTO (Link Time Optimization):
+```bash
+LTO=OFF make debug.linux -j
+```
+
+### Checking Patch
+```bash
+make precommit -j
+```
+If some style guidelines, build or test runs fail during precommit, then this is indicated with a message like this:
+```
+Build failed. See ./build/bin/unittests/make.log for details.
+```