diff --git a/docs/build/cmake_flags.md b/docs/build/cmake_flags.md index e1c011ac4..c6e9305b8 100644 --- a/docs/build/cmake_flags.md +++ b/docs/build/cmake_flags.md @@ -11,7 +11,7 @@ cmake --build --preset Additionally you can use `-DSC_BUILD_BENCH=ON` flag to build performance tests -## Building with sanitizers +## Building sc-machine with sanitizers Use `cmake` with `-DSC_USE_SANITIZER=memory` or `-DSC_USE_SANITIZER=address` option to run build with memory or address sanitizer. diff --git a/docs/build/quick_start.md b/docs/build/quick_start.md new file mode 100644 index 000000000..195d62203 --- /dev/null +++ b/docs/build/quick_start.md @@ -0,0 +1,223 @@ +# Quick start + +This guide provides short information for developers to start to work with sc-machine quickly. You can always learn more about the sc-machine's [build system](build_system.md). + +## Check CMake + +Ensure you are using **CMake version 3.24** or newer. Verify your version with: + +```sh +cmake --version +``` + +To upgrade CMake, follow the installation guide appropriate for your OS or use: + +```sh +# Use pipx to install cmake if not already installed +# Install pipx first using guide: https://pipx.pypa.io/stable/installation/ +pipx install cmake +``` + +## Start develop sc-machine with Conan + +### Install Conan + +Install Conan, to build sc-machine dependencies with Conan-provided dependencies: + +```sh +# Use pipx to install conan if not already installed +pipx install conan +``` + +### Use sc-machine in Debug + +#### Build sc-machine in Debug + +To build sc-machine in debug mode using Conan-provided dependencies, run: + +```sh +# debug build type +cmake --preset debug-conan +cmake --build --preset debug +``` + +Note: By default, configure preset `debug` enables building sc-machine tests. + +#### Run sc-machine tests in Debug + +After that, you can go to `build/Debug` and run tests via `ctest`: + +```sh +cd build/Debug +ctest -V Debug +``` + +#### Run sc-machine in Debug + +```sh +# create empty knowledge base sources folder +mkdir kb +# note: at this stage you can move your KB sources to the ./kb folder + +# build knowledge base +./build/Debug/bin/sc-builder -i kb -o kb.bin --clear +# run sc-machine +./build/Debug/bin/sc-machine -e build/Debug/lib/extensions -s kb.bin +``` + +### Use sc-machine in Release + +#### Build sc-machine in Release + +To build sc-machine in release mode using Conan-provided dependencies, run: + +```sh +# release build type without tests +cmake --preset release-conan +cmake --build --preset release +``` + +To build sc-machine with tests in release mode using Conan-provided dependencies, run: + +```sh +# release build type with tests +cmake --preset release-with-tests-conan +cmake --build --preset release +``` + +#### Run sc-machine tests in Release + +After that, you can run tests: + +```sh +cd build/Release +ctest -V Release +``` + +#### Run sc-machine in Release + +```sh +# create empty knowledge base sources folder +mkdir kb +# note: at this stage you can move your KB sources to the ./kb folder + +# build knowledge base +./build/Release/bin/sc-builder -i kb -o kb.bin --clear +# run sc-machine +./build/Release/bin/sc-machine -e build/Release/lib/extensions -s kb.bin +``` + +You can also check code formatting, build sc-machine with sanitizers and other. To learn more, go to the [CMake flags](cmake_flags.md) page. + +## Start develop sc-machine with system-provided dependencies + +### Install sc-machine dependencies + +Note: sc-machine build system supports installation of dependencies for Ubuntu and macOS only. + +#### Install sc-machine dependencies for Ubuntu + +```sh +cd scripts +./install_deps_ubuntu.sh +``` + +#### Install sc-machine dependencies for macOS + +```sh +cd scripts +./install_deps_macOS.sh +``` + +#### Install sc-machine dependencies for other OS + +Currently, we require the following packages to be available to CMake at build-time: + +- `java` +- `glib2` +- `websocketpp` + - [`asio`](https://think-async.com/Asio/) as the transitive dependency +- `nlohmann_json` +- `xml2` + +You can try install these dependencies on your OS. + +### Use sc-machine in Debug + +#### Build sc-machine in Debug + +To build sc-machine in debug mode using system-provided dependencies, run: + +```sh +# debug build type +cmake --preset debug +cmake --build --preset debug +``` + +Note: By default, configure preset `debug` enables building sc-machine tests. + +#### Run sc-machine tests in Debug + +After that, you can go to `build/Debug` and run tests via `ctest`: + +```sh +cd build/Debug +ctest -V Debug +``` + +#### Run sc-machine in Debug + +```sh +# create empty knowledge base sources folder +mkdir kb +# note: at this stage you can move your KB sources to the ./kb folder + +# build knowledge base +./build/Debug/bin/sc-builder -i kb -o kb.bin --clear +# run sc-machine +./build/Debug/bin/sc-machine -e build/Debug/lib/extensions -s kb.bin +``` + +### Use sc-machine in Release + +#### Build sc-machine in Release + +To build sc-machine in release mode using system-provided dependencies, run: + +```sh +# release build type without tests +cmake --preset release +cmake --build --preset release +``` + +To build sc-machine with tests in release mode using system-provided dependencies, run: + +```sh +# release build type with tests +cmake --preset release-with-tests +cmake --build --preset release +``` + +#### Run sc-machine tests in Release + +After that, you can run tests: + +```sh +cd build/Release +ctest -V Release +``` + +#### Run sc-machine in Release + +```sh +# create empty knowledge base sources folder +mkdir kb +# note: at this stage you can move your KB sources to the ./kb folder + +# build knowledge base +./build/Release/bin/sc-builder -i kb -o kb.bin --clear +# run sc-machine +./build/Release/bin/sc-machine -e build/Release/lib/extensions -s kb.bin +``` + +You can also check code formatting, build sc-machine with sanitizers and other. To learn more, go to the [CMake flags](cmake_flags.md) page. diff --git a/docs/index.md b/docs/index.md index b46507ef0..3f4d9c132 100644 --- a/docs/index.md +++ b/docs/index.md @@ -41,6 +41,7 @@ Table of contents: * [Knowledge Base repo file](sc-tools/kb_repo_file.md) - *description of configuration of knowledge base sources* * [sc-machine Runner](sc-tools/sc_machine.md) - *description of options of sc-machine runner* - **Developer instructions** - *guidelines for building the project, configuring settings* + * [Quick start](build/quick_start.md) - *get up and start developing sc-machine quickly* * [Build system](build/build_system.md) - *how to build the project and use it as a library* * [CMake Flags](build/cmake_flags.md) - *description of CMake flags used to configure sc-machine* * [Configuration File](build/config.md) - *description of a configuration file of sc-machine* diff --git a/mkdocs.yml b/mkdocs.yml index 0e16e8094..e09e5bdda 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,6 +41,7 @@ nav: - Knowledge Base repo file: sc-tools/kb_repo_file.md - sc-machine Runner: sc-tools/sc_machine.md - Developer guides: + - Quick start: build/quick_start.md - Build system: build/build_system.md - CMake flags: build/cmake_flags.md - Configuration file: build/config.md