Update README

Signed-off-by: HyukWoo Park <[email protected]>
Samsung · Aug 20, 2024 · 89e66fd · 89e66fd
1 parent 2ec730b
commit 89e66fd
Showing 1 changed file with 93 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -6,9 +6,55 @@
 [![Coverity Scan Build Status](https://scan.coverity.com/projects/21647/badge.svg)](https://scan.coverity.com/projects/samsung-escargot)
 [![codecov](https://codecov.io/gh/Samsung/escargot/branch/master/graph/badge.svg?token=DX8CN6E7A8)](https://codecov.io/gh/Samsung/escargot)
 
-## Prerequisites
 
-#### On Ubuntu Linux
+Escargot is a lightweight JavaScript engine developed by [Samsung](https://github.com/Samsung), designed specifically for resource-constrained environments. It is optimized for performance and low memory usage, making it ideal for use in embedded systems, IoT devices, and other applications where resources are limited.
+
+Key features of Escargot include:
+* **ECMAScript Compliance**: Escargot supports a significant portion of the latest ECMAScript version ([ECMAScript 2024](https://262.ecma-international.org/15.0/)), ensuring compatibility with modern JavaScript standards while maintaining a lightweight footprint.
+* **Memory Efficiency**: The engine is designed with memory constraints in mind, making it suitable for devices with limited RAM and storage.
+* **Performance Optimization**: Escargot implements various optimization techniques to ensure fast execution of JavaScript code, even on low-power devices.
+* **Extensibility**: The engine can be customized and extended to meet the specific needs of different applications, providing flexibility for developers.
+
+Escargot is an open-source project that allows developers to contribute to its development or use it in their own projects, while also powering several services in Samsung products. The engine's design prioritizes simplicity and efficiency, making it an excellent choice for developers working in embedded or resource-limited environments.
+
+
+## Contents 📋
+* [Building](#Building-)
+  * [Linux](#Linux)
+  * [Mac OS](#Mac-OS)
+  * [Android](#Android)
+  * [Windows](#Windows)
+* [Testing](#Testing-)
+* [Contributing](#Contributing-)
+* [Research Papers](#Research-Papers-)
+* [License](#License-)
+
+## Building 🛠️
+
+#### Build Options
+
+The following build options are supported when generating ninja rules using cmake.
+
+* -DESCARGOT_HOST=[ linux | tizen_obs | darwin | android | windows ]<br>
+  Compile Escargot for Linux, Tizen, macOS, or Windows platform
+* -DESCARGOT_ARCH=[ x64 | x86 | arm | i686 | aarch64 ]<br>
+  Compile Escargot for each architecture
+* -DESCARGOT_MODE=[ debug | release ]<br>
+  Compile Escargot for either release or debug mode
+* -DESCARGOT_OUTPUT=[ shared_lib | static_lib | shell | cctest ]<br>
+  Define target output type
+* -DESCARGOT_LIBICU_SUPPORT=[ ON | OFF ]<br>
+  Enable libicu library if set ON. (Optional, default = ON)
+* -DESCARGOT_THREADING=[ ON | OFF ]<br>
+  Enable Threading support. (Optional, default = OFF)
+* -DESCARGOT_CODE_CACHE=[ ON | OFF ]<br>
+  Enable Code cache support. (Optional, default = OFF)
+* -DESCARGOT_WASM=[ ON | OFF ]<br>
+  Enable WASM support. (Optional, default = OFF)
+* -DESCARGOT_SMALL_CONFIG=[ ON | OFF ]<br>
+  Enable Options for small devices. (Optional, default = OFF)
+
+#### Linux
 
 General build prerequisites:
 ```sh
@@ -21,33 +67,37 @@ sudo apt-get install gcc-multilib g++-multilib
 sudo apt-get install libicu-dev:i386
 ```
 
-#### On macOS
+Build Escargot:
+```sh
+git submodule update --init third_party # update submodules
+cmake -DESCARGOT_MODE=release -DESCARGOT_OUTPUT=shell -GNinja
+ninja
+```
+
+#### Mac OS
 
+General build prerequisites:
 ```sh
 brew install autoconf automake cmake icu4c libtool ninja pkg-config
 ```
 
-## Build Escargot
-
+Build Escargot:
 ```sh
-git clone https://github.com/Samsung/escargot.git
-cd escargot
-git submodule update --init third_party
+git submodule update --init third_party # update submodules
 cmake -DESCARGOT_MODE=release -DESCARGOT_OUTPUT=shell -GNinja
 ninja
 ```
 
-## Build Android version
+#### Android
 
 Build prerequisites on Ubuntu:
 ```sh
 sudo apt install openjdk-17-jdk # require java 17
 ```
 
+Build Escargot using gradle:
 ```sh
-git clone https://github.com/Samsung/escargot.git
-cd escargot
-git submodule update --init third_party
+git submodule update --init third_party # update submodules
 export ANDROID_SDK_ROOT=.... # set your android SDK root first
 cd build/android/
 ./gradlew bundleReleaseAar # build escargot AAR
@@ -60,54 +110,51 @@ cd build/android/
 ./gradlew :escargot:testDebugUnitTest # run escargot-jni tests on host
 ```
 
-## Build Windows version
+#### Windows
 
 Install VS2022 with cmake and ninja.
 Open [ x86 Native Tools Command Prompt for VS 2022 | x64 Native Tools Command Prompt for VS 2022 ]
+
 ```sh
-git clone https://github.com/Samsung/escargot.git
-cd escargot
-git submodule update --init third_party
+git submodule update --init third_party # update submodules
 
 CMake -G "Visual Studio 17 2022" -DCMAKE_SYSTEM_NAME=[ Windows | WindowsStore ] -DCMAKE_SYSTEM_VERSION:STRING="10.0"  -DCMAKE_SYSTEM_PROCESSOR=[ x86 | x64 ] -DCMAKE_GENERATOR_PLATFORM=[ Win32 | x64 ],version=10.0.18362.0 -DESCARGOT_ARCH=[ x86 | x64 ] -DESCARGOT_MODE=release -Bout -DESCARGOT_HOST=windows -DESCARGOT_OUTPUT=shell -DESCARGOT_LIBICU_SUPPORT=ON -DESCARGOT_LIBICU_SUPPORT_WITH_DLOPEN=OFF -DESCARGOT_THREADING=ON
 cd out
 msbuild ESCARGOT.sln /property:Configuration=Release /p:platform=[ Win32 | x64 ]
 ```
 
-#### Build options
-
-The following build options are supported when generating ninja rules using cmake.
+## Testing ✅
 
-* -DESCARGOT_HOST=[ linux | tizen_obs | darwin | android | windows ]<br>
-  Compile Escargot for Linux, Tizen, macOS, or Windows platform
-* -DESCARGOT_ARCH=[ x64 | x86 | arm | i686 | aarch64 ]<br>
-  Compile Escargot for each architecture
-* -DESCARGOT_MODE=[ debug | release ]<br>
-  Compile Escargot for either release or debug mode
-* -DESCARGOT_OUTPUT=[ shared_lib | static_lib | shell | cctest ]<br>
-  Define target output type
-* -DESCARGOT_LIBICU_SUPPORT=[ ON | OFF ]<br>
-  Enable libicu library if set ON. (Optional, default = ON)
-* -DESCARGOT_THREADING=[ ON | OFF ]<br>
-  Enable Threading support. (Optional, default = OFF)
-* -DESCARGOT_CODE_CACHE=[ ON | OFF ]<br>
-  Enable Code cache support. (Optional, default = OFF)
-* -DESCARGOT_WASM=[ ON | OFF ]<br>
-  Enable WASM support. (Optional, default = OFF)
-* -DESCARGOT_SMALL_CONFIG=[ ON | OFF ]<br>
-  Enable Options for small devices. (Optional, default = OFF)
+Escargot supports various benchmark sets, which can be run using the [tools/run-tests.py](https://github.com/Samsung/escargot/blob/master/tools/run-tests.py) script.
 
-## Testing
+| Benchmark | flag |
+| --- | --- |
+| SunSpider 1.0.2 | `sunspider` |
+| [Octane 2.0](https://github.com/chromium/octane.git) | `octane` |
+| [test262](https://github.com/tc39/test262.git) | `test262` |
+| [Web Tooling Benchmark](https://github.com/v8/web-tooling-benchmark) | `web-tooling-benchmark` |
+| SpiderMonkey (vendor-made) | `spidermonkey` |
+| ChakraCore (vendor-made) | `chakracore` |
+| V8 (vendor-made) | `v8` |
 
-First, get benchmarks and tests:
+Run each benchmark separately or all together as shown below:
 ```sh
-git submodule update --init
+tools/run-tests.py --engine=./out/linux/x64/release/escargot web-tooling-benchmark
+tools/run-tests.py --engine=./out/linux/x64/release/escargot spidermonkey test262 v8
 ```
 
-### Benchmarks
+## Contributing 💡
+Escargot welcomes contributions from developers in any form, wheter it's code, documentation, bug reports, or suggestions. By contributing to the project, you agree to license your contributions under the [LGPL-2.1](https://github.com/Samsung/escargot/blob/master/LICENSE) license.
 
-Test run for each benchmark (Sunspider, Octane, V8, Chakracore, test262,
-SpiderMonkey, etc.):
-```sh
-tools/run-tests.py --arch=x86_64 spidermonkey test262 v8
-```
+#### ❗ Vulnerability Reporting
+⚠️ If you identify any vulnerabilities, please report them through the [Issues page](https://github.com/Samsung/escargot/issues). *We may not accept reports through any other channels*. Please note that our project assumes the execution of valid JavaScript source code only. Handling of invalid source code is not within the scope of this project.
+
+## Research Papers 📝
+* [Dynamic code compression for JavaScript engine](https://doi.org/10.1002/spe.3186)  
+  Software: Practice and Experience Vol. 53 (5), pp. 1196-1217, 2023
+
+* [Tail Call Optimization Tailored for Native Stack Utilization in JavaScript Runtimes](https://doi.org/10.1109/ACCESS.2024.3441750)  
+  IEEE Access Vol. 12, pp. 111801-111817, 2024
+
+## License 📜
+Escargot is open-source software primarily licensed under [LGPL-2.1](https://github.com/Samsung/escargot/blob/master/LICENSE), with some components covered by other licenses. Complete license and copyright information can be found in the source code.