github.com/igggame/nebulas-go@v2.1.0+incompatible/nbre/README.md (about)

     1  
     2  ## Overview
     3  
     4  ## NBRE Architecture
     5  
     6  ![nbre_construct.jpg](https://github.com/nebulasio/go-nebulas/raw/feature/nbre/nbre/doc/jpg/nbre_construct.jpg)
     7  
     8  ## NBRE Modules
     9  * common
    10  * fs
    11  * core
    12  * jit
    13  * cmd
    14  
    15  ## Build NBRE From Scratch
    16  * Set Up Build Environment:
    17    Go to directory "go-nebulas/nbre", then execute script "prepare.sh"
    18    This step will compile all the 3rd-party libraries that nbre depends on, and the applications used to compile NBRE source code
    19    Afterwards, set up environment variables accordingly
    20  
    21  ```
    22  $> cd go-nebulas/nbre
    23  $> ./prepare.sh
    24  $> source env.set.sh
    25  ```
    26  
    27  * Compile NBRE source code
    28    Create directory "build", then generate makefile via cmake
    29  ```
    30  $> mkdir build
    31  $> cd build
    32  $> cmake --CMAKE_BUILD_TYPE=Release ../
    33  ```
    34  
    35  * NBRE Configuration
    36    * configuration of nasir
    37  ```
    38  {
    39    "name": "nr",
    40    "version_major": 0,
    41    "version_minor": 0,
    42    "version_patch": 1,
    43    "depends": [
    44    ],
    45    "available_height": 100,
    46    "cpp_files": [
    47      "test/link_example/foo_arg.cpp"
    48    ],
    49    "include_header_files":[
    50      "test/link_example"
    51    ],
    52    "link_path":[
    53    ],
    54    "link_files":[
    55    ],
    56    "flags": [
    57    ]
    58  }
    59  ```
    60  
    61  |Label|Meaning|
    62  |---|:---|
    63  |version_major| major version number |
    64  |version_minor| minor version number |
    65  |version_patch| patch version number |
    66  |depends| dependancies |
    67  |available_height| height that the ir takes effect |
    68  |cpp_files| c++ implementation of core protocols |
    69  |include_header_files| c++ header files of core protocols implementation |
    70  |link_path| linking path(s) |
    71  |link_files| linking file(s) |
    72  |flags| compiling parameters |
    73  
    74  * Database Configuration 
    75    * Edit file "env.set.sh" to add the following line at the end
    76  ```
    77  export NBRE_DB=go-nebulas/data.db
    78  ```
    79  
    80  ## Module common
    81  * ipc(inter process communication)
    82    basic functionalities of neb_ipc, including: bookkeeper, service, session, queue etc.
    83  * util
    84    * bytes: base58 and base64 encoding and decoding functionalities
    85    * enable_func_if: templates for checking function types
    86    * singleton: singleton templates
    87    * version: version management
    88  * configuration: read ini file and get parameters of JIT
    89  * ir_conf_reader: read json file and get parameters of nasir
    90  * quitable_thread: exception handling and thread exit
    91  
    92  ## Module fs
    93  * Inheritance relationship between fs classes 
    94  
    95  ![nbre_fs.jpg](https://github.com/nebulasio/go-nebulas/raw/feature/nbre/nbre/doc/jpg/nbre_fs.jpg)
    96  
    97  * rocksdb_storage: rocksdb related operations
    98  * nbre_storage: read/write blockchain related info based on rocksdb_storage
    99  * blockchain: transaction and block data
   100  * protocol buffer
   101  
   102  | file | meaning |
   103  |---|:---|
   104  |ir.proto| meta data of ir, including: name, version, effective height, dependancies etc. |
   105  |dag.proto| dag data structure |
   106  |state.proto| state data structure |
   107  |block.proto.patch| block data structure |
   108  
   109  * util
   110  
   111  ## Module core
   112  * Version management
   113  Every 15 seconds, ir_warden will query the block info, and update the ir version number if necessary
   114  
   115  * neb_ipc
   116    Inter process communication between NBRE and Neb
   117  
   118  * Check the following flowchat to see the functionalities of version management and ipc
   119  
   120  
   121  ![nbre_ipc.jpg](https://github.com/nebulasio/go-nebulas/blob/feature/nbredev/nbre/doc/jpg/nbre_ipc.jpg)
   122  
   123  ## Module JIT
   124  NBRE JIT is based on LLVM, core protocol IR is running on it.
   125  
   126  * NBRE execution time order
   127  
   128  
   129  ![nbre_jit_sequence.jpg](https://github.com/nebulasio/go-nebulas/raw/feature/nbre/nbre/doc/jpg/nbre_jit_sequence.jpg)
   130  
   131    * jit_driver
   132      jit_driver serves as the entry of JIT
   133  
   134  ## Module cmd
   135    * nasir
   136      generate ir, more specifically: 
   137  
   138  ```
   139  Generate IR Payload:
   140    --help show help message
   141    --input arg IR configuration file
   142    --output arg output file
   143    --mode arg (=payload) Generate ir bitcode or ir payload. - [bitcode |
   144                          payload], default:payload
   145  
   146  ```
   147  * payload mode (default mode): carry on the name, version etc, which can be executed directly on JIT.
   148  * bitcode mode: it generates the pure IR code, cannot be executed on JIT, just used for debugging.