Add examples to documentation

docs/docs/getting_started.md

@@ -31,10 +31,13 @@ In this case, updating requires downloading a new archive and replacing the dire
 > You can also download prebuilt binaries from our build server (see [Prebuilt Binaries](prebuilt_binaries.md)). Extract the archive to a directory and skip this section.
 
 The recommended way to build the Brisk library is with Ninja:
+
 ```bash
 cd path/to/brisk/repo
-cmake -GNinja -S . -B build -DCMAKE_INSTALL_PREFIX=dist -DCMAKE_BUILD_TYPE=RelWithDebInfo
-cmake --build build --config RelWithDebInfo --target install
+cmake -GNinja -S . -B build-release -DCMAKE_INSTALL_PREFIX=dist -DCMAKE_BUILD_TYPE=Release
+cmake --build build-release --target install
+cmake -GNinja -S . -B build-debug -DCMAKE_INSTALL_PREFIX=dist -DCMAKE_BUILD_TYPE=Debug
+cmake --build build-debug --target install
 ```
 
 `CMAKE_INSTALL_PREFIX` specifies the directory where the static libraries and header files will be placed after building.

docs/docs/hello_world.md

@@ -0,0 +1,124 @@
+# "Hello, World" GUI Application with Brisk
+
+This tutorial will guide you through creating a basic "Hello, World" application using the Brisk framework.
+
+## Prerequisites
+
+Either build or download the Brisk binaries and required dependencies. Refer to the [Getting Started](getting_started.md) tutorial for detailed instructions.
+
+## Step 1: Create the Project Files
+
+The "Hello, World" project will consist of three main files:
+
+1. `CMakeLists.txt` – Project setup
+2. `main.cpp` – Application code
+3. `icon.png` – Brisk icon (must be in PNG format, with a minimum size of 512x512). Download an example icon from /~https://github.com/brisklib/brisk-helloworld/raw/main/icon.png.
+
+### CMakeLists.txt
+
+Create a `CMakeLists.txt` file in your project directory with the following contents:
+
+```cmake
+# Minimum supported CMake version is 3.16
+cmake_minimum_required(VERSION 3.16)
+
+project(HelloWorldApp)
+
+# Locate Brisk libraries and headers
+find_package(Brisk CONFIG REQUIRED)
+
+# Define application metadata
+brisk_metadata(
+    VENDOR "Brisk"                     # Vendor or company name
+    NAME "HelloWorldApp"               # Application name
+    DESCRIPTION "Brisk Hello World"    # Short application description
+    VERSION "0.1.0"                    # Version number
+    COPYRIGHT "© 2024 Brisk"           # Copyright information
+    ICON ${CMAKE_SOURCE_DIR}/icon.png  # Path to the icon (PNG)
+    APPLE_BUNDLE com.brisklib.helloworld # Apple bundle identifier
+)
+
+# Create an executable target 'main' from main.cpp
+add_executable(main main.cpp)
+
+# Link necessary Brisk libraries to 'main'
+target_link_libraries(main PRIVATE brisk-widgets brisk-executable)
+
+# Set up the executable 'main' with Brisk icons, metadata, and startup/shutdown code
+brisk_setup_executable(main)
+```
+
+### main.cpp
+
+Create a `main.cpp` file in the same directory with the following code:
+
+```cpp
+#include <brisk/gui/Component.hpp>
+#include <brisk/gui/GUIApplication.hpp>
+#include <brisk/widgets/Graphene.hpp>
+#include <brisk/widgets/Button.hpp>
+#include <brisk/widgets/Layouts.hpp>
+#include <brisk/widgets/Text.hpp>
+
+using namespace Brisk;
+
+// Root component of the application, inherits from Brisk's Component class
+class RootComponent : public Component {
+public:
+  // Builds the UI layout for the component
+  RC<Widget> build() final {
+    return rcnew VLayout{
+        stylesheet = Graphene::stylesheet(), // Apply the default stylesheet
+        Graphene::darkColors(),              // Use dark color scheme
+        gapRow = 8_px,                       // Set vertical gap between elements
+        alignItems = AlignItems::Center,     // Align child widgets to the center
+        justifyContent = Justify::Center,    // Center the layout in the parent
+        new Text{"Hello, world"},            // Display a text widget with "Hello, world"
+        new Button{
+            new Text{"Quit"},                // Button label
+            onClick = m_lifetime | []() {    // Quit the application on button click
+                windowApplication->quit();
+            },
+        },
+    };
+  }
+};
+
+// Entry point of the Brisk application
+int briskMain() {
+  GUIApplication application; // Create the GUI application
+  return application.run(createComponent<RootComponent>()); // Run with RootComponent as main component
+}
+```
+
+### icon.png
+
+Place an icon named `icon.png` in your project directory. You can download an example from [this link](/~https://github.com/brisklib/brisk-helloworld/raw/main/icon.png).
+
+## Step 2: Build the Application
+
+With all files in place, you can now build the project.
+
+1. Open a terminal in your project directory.
+2. Run the following commands to create a build directory, configure the project, set the required CMake variables, and build the executable:
+
+   ```bash
+   mkdir build
+   cmake -S . -B build \
+     -DCMAKE_PREFIX_PATH=<path-to-brisk/lib/cmake> \
+     -DCMAKE_TOOLCHAIN_FILE=<path-to-vcpkg/scripts/buildsystems/vcpkg.cmake> \
+     -DVCPKG_INSTALLED_DIR=<path-to-vcpkg-installed>
+   cmake --build build
+   ```
+
+   For Windows you should also set the triplet: `-DVCPKG_TARGET_TRIPLET=x64-windows-static-md`.
+
+   Replace `path-to-brisk/lib/cmake` with the actual path to the `lib/cmake` directory inside the Brisk package, `<path-to-vcpkg/scripts/buildsystems/vcpkg.cmake>` with the path to the Vcpkg toolchain file, and `<path-to-vcpkg-installed>` with the path to your Vcpkg `installed` directory.
+
+3. After a successful build, you should have an executable named `main` in the build directory.
+
+## Step 3: Run the Application
+
+Execute the `main` file to run the application. You should see a window displaying "Hello, World" text with a "Quit" button that closes the application when clicked.
+
+Congratulations! You've built your first "Hello, World" application with Brisk.

docs/docs/index.md

@@ -8,6 +8,11 @@ The Brisk library is in the alpha stage, so there may be breaking changes, and t
 * [Installing Prerequisites](prerequisites.md)
 * [Prebuilt Binaries](prebuilt_binaries.md)
 
+## Examples
+
+* [Hello, world example](hello_world.md)
+* [Other examples](other_examples.md)
+
 ## Reference
 
 > [!note] 

docs/docs/other_examples.md

@@ -0,0 +1,6 @@
+# Brisk examples
+
+See the `examples` directory in the Brisk repository for advanced examples of using the Brisk framework.
+
+/~https://github.com/brisklib/brisk/tree/main/examples
+