Remove cchost binary - each library becomes an executable (#7128)

Author: eddyashton

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [7.0.0-dev2]
+
+[7.0.0-dev2]: https://github.com/microsoft/CCF/releases/tag/ccf-7.0.0-dev2
+
+### Changed
+
+- `cchost` is removed, and each application now provides its own executable:
+  - CCF nodes no longer contain a separate `cchost` executable and enclave library (`.so`) file. Each former enclave library is now its own executable, currently sharing the same set configuration format as the previous `cchost`.
+  - The `js_generic` sample app is no longer a library installed at `/ccf/lib/libjs_generic.so`, it is now an executable installed at `/ccf/bin/js_generic`.
+  - The `add_ccf_app` function in CMake now builds an executable rather than a library. The caller should provide a `main` function, and call `ccf::run()` from `include/ccf/run.h` to start the node (see `samples/apps/main.cpp` for a minimal example).
+- Application logging no longer traverses the ringbuffer. As current target platforms do not require distinct enclave and host components, what was previously "in-enclave" logging that was deferred via the ringbuffer can now be immediately sent to stdout.
+
 ## [7.0.0-dev1]
 
 [7.0.0-dev1]: https://github.com/microsoft/CCF/releases/tag/ccf-7.0.0-dev1

CMakeLists.txt

@@ -243,11 +243,11 @@ else()
   list(APPEND CCHOST_SOURCES src/host/snmalloc.cpp)
 endif()
 
-list(APPEND CCHOST_SOURCES ${CCF_DIR}/src/host/main.cpp
+list(APPEND CCHOST_SOURCES ${CCF_DIR}/src/host/run.cpp
      ${CCF_DIR}/src/host/env.cpp
 )
 
-add_executable(cchost ${CCHOST_SOURCES})
+add_library(cchost STATIC ${CCHOST_SOURCES})
 
 add_san(cchost)
 add_tidy(cchost)
@@ -272,8 +272,13 @@ target_link_libraries(
           http_parser
 )
 target_compile_definitions(cchost PRIVATE CCF_LOGGER_NO_DEPRECATE)
+set_property(TARGET cchost PROPERTY POSITION_INDEPENDENT_CODE ON)
 
-install(TARGETS cchost DESTINATION bin)
+install(
+  TARGETS cchost
+  EXPORT ccf
+  DESTINATION lib
+)
 
 # HTTP parser
 add_library(http_parser "${HTTP_PARSER_SOURCES}")
@@ -388,8 +393,8 @@ set(CCF_NETWORK_TEST_ARGS --log-level ${TEST_LOGGING_LEVEL} --worker-threads
 
 # SNIPPET_START: JS generic application
 add_ccf_app(
-  js_generic SRCS ${CCF_DIR}/src/apps/js_generic/js_generic.cpp INSTALL_LIBS
-                  ${CCF_DEVEL}
+  js_generic SRCS ${CCF_DIR}/src/apps/js_generic/js_generic.cpp
+                  ${CCF_DIR}/samples/apps/main.cpp INSTALL_LIBS ${CCF_DEVEL}
 )
 # SNIPPET_END: JS generic application
 
@@ -467,8 +472,6 @@ set(CCF_IMPL_SOURCE
 
 add_library(ccf STATIC ${CCF_IMPL_SOURCE})
 
-target_compile_definitions(ccf PUBLIC INSIDE_ENCLAVE VIRTUAL_ENCLAVE)
-
 target_compile_options(ccf PUBLIC ${COMPILE_LIBCXX})
 target_compile_definitions(ccf PRIVATE CCF_LOGGER_NO_DEPRECATE)
 
@@ -821,7 +824,10 @@ if(BUILD_TESTS)
     )
 
     # Merkle Tree memory test
-    add_executable(merkle_mem src/node/test/merkle_mem.cpp)
+    add_executable(
+      merkle_mem src/node/test/merkle_mem.cpp
+                 ${CCF_DIR}/src/enclave/thread_local.cpp
+    )
     target_compile_options(merkle_mem PRIVATE ${COMPILE_LIBCXX})
     target_link_libraries(
       merkle_mem PRIVATE ${CMAKE_THREAD_LIBS_INIT} ${LINK_LIBCXX} ccfcrypto
@@ -980,18 +986,16 @@ if(BUILD_TESTS)
       NAME modules_test
       PYTHON_SCRIPT ${CMAKE_SOURCE_DIR}/tests/js-modules/modules.py
       ADDITIONAL_ARGS
-        --package
-        libjs_generic
-        --election-timeout-ms
-        10000 # Larger election timeout as recording
+        --package js_generic --election-timeout-ms 10000 # Larger election
+                                                         # timeout as recording
         # large JS applications may trigger leadership changes
     )
 
     add_e2e_test(
       NAME auth
       PYTHON_SCRIPT
         ${CMAKE_SOURCE_DIR}/tests/js-custom-authorization/custom_authorization.py
-      ADDITIONAL_ARGS --package libjs_generic --js-app-bundle
+      ADDITIONAL_ARGS --package js_generic --js-app-bundle
                       ${CMAKE_SOURCE_DIR}/tests
     )
 
@@ -1240,15 +1244,15 @@ if(BUILD_TESTS)
       NAME pi_ls
       PYTHON_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/tests/infra/piccolo_driver.py
       CLIENT_BIN ./submit PERF_LABEL "Logging"
-      ADDITIONAL_ARGS --package "samples/apps/logging/liblogging"
+      ADDITIONAL_ARGS --package "samples/apps/logging/logging"
                       --max-writes-ahead 1000 --repetitions 10000
     )
 
     add_piccolo_test(
       NAME pi_basic
       PYTHON_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/tests/infra/basicperf.py
       CLIENT_BIN ./submit PERF_LABEL "Basic"
-      ADDITIONAL_ARGS --package "samples/apps/basic/libbasic" --client-def
+      ADDITIONAL_ARGS --package "samples/apps/basic/basic" --client-def
                       "1,write,100000,primary"
     )
 
@@ -1265,7 +1269,7 @@ if(BUILD_TESTS)
         NAME pi_basic_mt
         PYTHON_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/tests/infra/basicperf.py
         CLIENT_BIN ./submit PERF_LABEL "Basic Multi-Threaded"
-        ADDITIONAL_ARGS --package "samples/apps/basic/libbasic" --client-def
+        ADDITIONAL_ARGS --package "samples/apps/basic/basic" --client-def
                         "${WORKER_THREADS},write,100000,primary"
       )
     endif()
@@ -1276,7 +1280,7 @@ if(BUILD_TESTS)
       CLIENT_BIN ./submit PERF_LABEL "Logging JWT"
       ADDITIONAL_ARGS
         --package
-        "samples/apps/logging/liblogging"
+        "samples/apps/logging/logging"
         --max-writes-ahead
         1000
         --repetitions

cmake/ccf_app.cmake

@@ -21,16 +21,16 @@ function(add_ccf_app name)
     "SRCS;INCLUDE_DIRS;SYSTEM_INCLUDE_DIRS;LINK_LIBS;DEPS;INSTALL_LIBS"
   )
 
-  # Build app "enclave", loaded as a shared library
-  add_library(${name} SHARED ${PARSED_ARGS_SRCS})
+  # Build app executable
+  add_executable(${name} ${PARSED_ARGS_SRCS})
 
   target_include_directories(${name} PRIVATE ${PARSED_ARGS_INCLUDE_DIRS})
   target_include_directories(
     ${name} SYSTEM PRIVATE ${PARSED_ARGS_SYSTEM_INCLUDE_DIRS}
   )
   add_warning_checks(${name})
 
-  target_link_libraries(${name} PRIVATE ${PARSED_ARGS_LINK_LIBS} ccf)
+  target_link_libraries(${name} PRIVATE ${PARSED_ARGS_LINK_LIBS} ccf cchost)
 
   if(NOT (SAN OR TSAN))
     target_link_options(${name} PRIVATE LINKER:--no-undefined)
@@ -52,9 +52,8 @@ function(add_ccf_app name)
   endif()
 
   if(${PARSED_ARGS_INSTALL_LIBS})
-    install(TARGETS ${name} DESTINATION lib)
+    install(TARGETS ${name} DESTINATION bin)
   endif()
-
 endfunction()
 
 function(add_host_library name)

cmake/common.cmake

@@ -226,7 +226,9 @@ function(add_picobench name)
     PARSE_ARGV 1 PARSED_ARGS "" "" "SRCS;INCLUDE_DIRS;LINK_LIBS"
   )
 
-  add_executable(${name} ${PARSED_ARGS_SRCS})
+  add_executable(
+    ${name} ${PARSED_ARGS_SRCS} ${CCF_DIR}/src/enclave/thread_local.cpp
+  )
 
   target_include_directories(${name} PRIVATE src ${PARSED_ARGS_INCLUDE_DIRS})
 

doc/architecture/request_flow.rst

@@ -187,7 +187,7 @@ For deployments where nodes are not directly accessible, redirections can still
       P->>P: Execute request
       P-->>U: 200 OK "Copied {a} from {A} to {B}"
 
-To use redirection behaviour, and choose whether to redirect to a node or a load balancer, set the ``redirections`` field in the :doc:`cchost launch configuration </operations/configuration>`.
+To use redirection behaviour, and choose whether to redirect to a node or a load balancer, set the ``redirections`` field in the :doc:`launch configuration </operations/configuration>`.
 
 External executor flow
 ----------------------

doc/architecture/threading.rst

@@ -17,7 +17,7 @@ Implementation
 Configuration
 ~~~~~~~~~~~~~
 
-To enable multiple worker threads, the ``worker_threads`` configuration option can be used  along with the number of desired threads to ``cchost`` when starting a CCF node.
+To enable multiple worker threads, the ``worker_threads`` configuration option can be set to the number of desired threads when starting a CCF node.
 
 It is strongly recommended that all CCF nodes run the same number of worker threads.
 The number of worker threads must be at least 1 less than the value of ``NumTCS`` in the oe_sign.conf file.

doc/build_apps/get_started.rst

@@ -32,7 +32,7 @@ CCF apps can be written in JavaScript/Typescript. To test a JS/TS CCF applicatio
 Build Application
 ~~~~~~~~~~~~~~~~~
 
-The application building prerequisites [:doc:`CCF </build_apps/install_bin>`, `NodeJS <https://nodejs.org>`__ and `NPM <https://www.npmjs.com>`__] must be installed, all will be preinstalled if you are using the devcontainer environment, otherwise you need to install them manually.
+The application building prerequisites (:doc:`CCF </build_apps/install_bin>`, `NodeJS <https://nodejs.org>`__ and `NPM <https://www.npmjs.com>`__) must be installed, all will be preinstalled if you are using the devcontainer environment, otherwise you need to install them manually.
 
 Please follow `ccf-app-template build process <https://github.com/microsoft/ccf-app-template#run-js-app>`__
 
@@ -43,22 +43,18 @@ There are several approaches to run and test your application.
 
 .. tab:: CCF sandbox
 
-   -  Running the `sandbox.sh` script automatically starts a CCF network and deploys your application on it. The app is up and ready to receive calls and the initial governance steps are done for you
-   -  Support both ccf network types [virtual - enclave (TEE hardware)]
-   -  No initial governance steps required
+   -  Running the `sandbox.sh` script automatically starts a CCF network and deploys your application on it. This will create appropriate configuration files and directory structures, and can be made to print each command for further detail. Once the network is initialised, this will print the node addresses you can use to interact with the service.
+   -  No manual governance steps required
 
       -  :doc:`/build_apps/run_app`
       -  `CCF Application template repository <https://github.com/microsoft/ccf-app-template#run-js-app>`__
 
-.. tab:: VM
+.. tab:: Direct launch
 
-   -  The application can be tested using ``cchost`` and :doc:`CCF config file </operations/configuration>`,
-      To Start a test CCF network on a Linux environment, it requires :doc:`CCF to be intalled </build_apps/install_bin>`.
-   -  Support both ccf network types [virtual - enclave (TEE hardware)]
-   -  Initial governance steps are required to initialize, deploy your app, and start the network. `check Network governance section <https://github.com/microsoft/ccf-app-template#network-governance>`__
+   -  The application can be run directly, given a :doc:`CCF config file </operations/configuration>`.
+      Some runtime dependencies are required, so ensure that :doc:`CCF is installed </build_apps/install_bin>`.
+   -  Governance steps are required to :doc:`initialize state, configure your app, and start the network </operations/start_network>`.
 
-      -  Start a CCF network using cchost and :doc:`CCF node config file </operations/configuration>`. please follow `ccf-app-template <https://github.com/microsoft/ccf-app-template#bare-vm>`__
-      -  The network is started with one node and one member, you need to execute the initial governance steps to initialize the network, `check Network governance section <https://github.com/microsoft/ccf-app-template#network-governance>`__ 
 
 Testing: Application Endpoints
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -73,7 +69,7 @@ C++ Applications
 
 CCF apps can also be written in C++. This offers better performance than JavaScript apps but requires a compilation step and a restart of the CCF node for deployment. please check `ccf-app-template <https://github.com/microsoft/ccf-app-template>`__ repository.
 
-The C++ sample app is located in the ```cpp/`` <cpp/>`__ directory.
+The C++ sample app is located in the `cpp/ <https://github.com/microsoft/ccf-app-template/tree/main/cpp>`__ directory.
 
 Build C++ app
 ~~~~~~~~~~~~~

doc/build_apps/install_bin.rst

@@ -24,7 +24,7 @@ The following commands can be run to verify that CCF was installed successfully:
 
 .. code-block:: bash
 
-    $ /opt/ccf/bin/cchost --version
+    $ /opt/ccf/bin/js_generic --version
     CCF host: ccf-<version>
     Platform: SNP
 
@@ -45,7 +45,7 @@ The following commands can be run to verify that CCF was installed successfully:
 
 The CCF install notably contains:
 
-- The ``cchost`` binary required to spin up a CCF application
+- A sample ``js_generic`` application built with CCF, which may be used to host JS applications
 - The ``cmake`` files required to build CCF applications
 - Header files and libraries to build CCF applications (under ``include/`` and ``lib/``)
 - A limited set of Python utilities to start a basic CCF service for local testing

doc/build_apps/run_app.rst

@@ -19,7 +19,7 @@ There are a large number of additional configuration options, documented by pass
 This script automates the steps described in :doc:`/operations/start_network`, in summary:
 
 - generating new identities (private keys and certs) for the initial members and users
-- starting the initial ``cchost`` node
+- starting the initial node
 - starting multiple additional nodes, instructed to ``join`` the initial node
 - verifying that each node has successfully joined the new service
 - proposing and passing governance votes using the generated member identities

doc/contribute/onboarding.rst

@@ -22,19 +22,19 @@ Walk through a sample application
 
 The logging application is simple, but exercises most features of the framework, and is extensively used in the end to end tests.
 
-To run a locally built copy of this application in a sandbox, see :doc:`/build_apps/run_app`. The package name will be ``samples/apps/logging/liblogging``:
+To run a locally built copy of this application in a sandbox, see :doc:`/build_apps/run_app`. The package name will be ``samples/apps/logging/logging``:
 
 .. code-block:: bash
 
-    ~/CCF/build$ ../tests/sandbox/sandbox.sh -p samples/apps/logging/liblogging
+    ~/CCF/build$ ../tests/sandbox/sandbox.sh -p samples/apps/logging/logging
 
     Setting up Python environment...
     Python environment successfully setup
     [11:44:33.376] Starting 1 CCF node...
     [11:44:33.376] Virtual mode enabled
     [11:44:35.025] Started CCF network with the following nodes:
     [11:44:35.025]   Node [0] = https://127.0.0.1:8000
-    [11:44:35.025] You can now issue business transactions to the samples/apps/logging/liblogging application
+    [11:44:35.025] You can now issue business transactions to the samples/apps/logging/logging application
     [11:44:35.025] Keys and certificates have been copied to the common folder: /home/$USER/CCF/build/workspace/sandbox_common
     [11:44:35.025] See https://microsoft.github.io/CCF/main/use_apps/issue_commands.html for more information
     [11:44:35.025] Press Ctrl+C to shutdown the network