Add initial examples (#636)

* Add initial examples

Signed-off-by: Uilian Ries <[email protected]>

* Fix examples description

Signed-off-by: Uilian Ries <[email protected]>

* Fix linker name

Signed-off-by: Uilian Ries <[email protected]>

---------

Signed-off-by: Uilian Ries <[email protected]>

.github/workflows/linux-clang-build.yml

@@ -72,13 +72,19 @@ jobs:
             -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
             -DCODE_COVERAGE:BOOL=ON \
             -DBUILD_TESTING:BOOL=ON \
+            -DBUILD_EXAMPLES:BOOL=ON \
             -DUSE_SYSTEM_DEPENDENCIES:BOOL=ON \
             -DUSE_STD_FORMAT:BOOL=ON \
             -DCMAKE_TOOLCHAIN_FILE=build/Debug/generators/conan_toolchain.cmake \
-            -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=gold
+            -DCMAKE_EXE_LINKER_FLAGS=-fuse-ld=lld
 
       - name: Build
         run: cmake --build --preset=unixlike-clang-debug
 
       - name: Test
         run: ctest --preset=unixlike-clang-debug
+
+      - name: Examples
+        run: |
+          cmake --build --preset=unixlike-clang-debug --target run-faker-cxx-basic-example \
+          && cmake --build --preset=unixlike-clang-debug --target run-faker-cxx-person-example

CMakeLists.txt

@@ -5,6 +5,7 @@ include(cmake/CompilerWarnings.cmake)
 
 option(USE_SYSTEM_DEPENDENCIES "Use fmt and GTest from system" OFF)
 option(USE_STD_FORMAT "Use std::format when avaiable" ON)
+option(BUILD_EXAMPLES "Build examples" OFF)
 
 if (USE_STD_FORMAT)
     set(CMAKE_REQUIRED_FLAGS -std=c++20)
@@ -137,3 +138,7 @@ endif ()
 if (BUILD_TESTING)
     add_subdirectory(tests)
 endif ()
+
+if (BUILD_EXAMPLES)
+    add_subdirectory(examples)
+endif ()

README.md

@@ -158,3 +158,13 @@ Before contributing please review
 our [CONTRIBUTING](https://github.com/cieslarmichal/faker-cxx/blob/main/CONTRIBUTING.md) guide.
 
 Additionally, we encourage you to join our [Discord Channel](https://discord.gg/h2ur8H6mK6) for contributors.
+
+## Examples
+
+This project offers examples to demonstrate how to use the Faker C++ library.
+These examples can be found in the [examples](examples/README.md) folder of the project repository.
+The examples showcase various modules of the library and provide code snippets that illustrate how to generate fake data using Faker C++.
+
+## License
+
+This project is under [MIT](LICENSE) license.

examples/CMakeLists.txt

@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.22)
+project(faker-cxx-examples LANGUAGES CXX)
+
+add_subdirectory(basic)
+add_subdirectory(person)

examples/README.md

@@ -0,0 +1,43 @@
+# Faker-cxx Examples
+
+This repository contains examples for using the Faker-cxx library.
+
+## Building with CMake
+
+To build the examples, you should follow the [CONTRIBUTING.md](../CONTRIBUTING.md) guide as usual,
+however you should pass `-DBUILD_EXAMPLE=ON` to CMake in order to build examples. It's disabled
+by default. For instance:
+
+```sh
+cmake -S . --preset <preset-name> -DBUILD_EXAMPLES=ON
+```
+
+## Running examples
+
+In order to run a built example application, you need to go to the build folder, then run the application:
+
+```
+cd build/<preset-name>/examples/person
+./faker-cxx-person-example
+```
+
+However, using CMake, you can execute all examples individually:
+
+```
+cmake --build --preset <preset-name> --target run-faker-cxx-person-example
+```
+
+The custom CMake target `run-faker-cxx-person-example` will run the faker-cxx-person-example.
+Only needs to add the prefix `run-` to the example name.
+
+## Examples:
+
+Here is a list of availables examples in this folder.
+
+### Basic
+
+It follows the main example listed in the [README.md](../README.md) root file.
+
+### Person
+
+The `Person` example demonstrates how to generate fake person data using the Faker-cxx library. It showcases various features and functions provided by the library to generate realistic person information.

examples/basic/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.22)
+project(faker-cxx-basic-example LANGUAGES CXX)
+
+add_executable(${PROJECT_NAME} ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp)
+target_link_libraries(${PROJECT_NAME} faker-cxx)
+
+add_custom_target(run-${PROJECT_NAME}
+    DEPENDS ${PROJECT_NAME}
+    COMMAND ${PROJECT_NAME}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Running ${PROJECT_NAME}"
+)

examples/basic/main.cpp

@@ -0,0 +1,24 @@
+#include <cstdlib>
+#include <iostream>
+
+#include "faker-cxx/Date.h"
+#include "faker-cxx/Internet.h"
+#include "faker-cxx/Location.h"
+#include "faker-cxx/String.h"
+
+int main()
+{
+    const auto id = faker::String::uuid();
+    const auto email = faker::Internet::email();
+    const auto password = faker::Internet::password();
+    const auto city = faker::Location::city();
+    const auto streetAddress = faker::Location::streetAddress();
+
+    std::cout << id << std::endl;
+    std::cout << email << std::endl;
+    std::cout << password << std::endl;
+    std::cout << city << std::endl;
+    std::cout << streetAddress << std::endl;
+
+    return EXIT_SUCCESS;
+}

examples/person/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.22)
+project(faker-cxx-person-example LANGUAGES CXX)
+
+add_executable(${PROJECT_NAME} ${CMAKE_CURRENT_SOURCE_DIR}/main.cpp)
+target_link_libraries(${PROJECT_NAME} faker-cxx)
+
+add_custom_target(run-${PROJECT_NAME}
+    DEPENDS ${PROJECT_NAME}
+    COMMAND ${PROJECT_NAME}
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+    COMMENT "Running ${PROJECT_NAME}"
+)

examples/person/main.cpp

@@ -0,0 +1,29 @@
+#include <cstdlib>
+#include <iostream>
+
+#include "faker-cxx/Person.h"
+
+int main() {
+    const auto personFullName = faker::Person::fullName();
+    std::cout << "Person full name: " << personFullName << std::endl;
+
+    const auto jobTitle = faker::Person::jobTitle();
+    std::cout << "Person job title: " << jobTitle << std::endl;
+
+    const auto hobby = faker::Person::hobby();
+    std::cout << "Person hobby: " << hobby << std::endl;
+
+    const auto language = faker::Person::language();
+    std::cout << "Person language: " << language << std::endl;
+
+    const auto nationality = faker::Person::nationality();
+    std::cout << "Person nationality: " << nationality << std::endl;
+
+    const auto chineseZodiac = faker::Person::chineseZodiac();
+    std::cout << "Person chinese zodiac: " << chineseZodiac << std::endl;
+
+    const auto passport = faker::Person::passport();
+    std::cout << "Person passport: " << passport << std::endl;
+
+    return EXIT_SUCCESS;
+}