При написании любой библиотеки очень важно предоставить пользователям рабочие примеры использования вашей библиотеки. Это позволит избежать лишних вопросов и сделает библиотеку удобнее для программистов.

В прошлой статье мы написали документацию для библиотеку C++ ColorConsole с использованием Doxygen. Сегодня мы добавим для неё примеры использования.

Настройка проекта

Начнем мы с проекта, размещенного в git-репозитории. Мы продолжим настройку проекта из прошлой статьи.

Если папка:

c:\project\colorconsolelib

уже существует, переместите или удалите её:

cd c:\projects
rmdir /q/s colorconsolelib

Мы будем использовать проект из git-репозитория:

cd c:\projects
rmdir /q/s articles_blog_altuninvv_ru
git clone https://gitflic.ru/project/vasiliyaltunin/articles_blog_altuninvv_ru.git --depth 1

Скопируем папку с проектом:

xcopy /y/e .\articles_blog_altuninvv_ru\qt6\libcolorconsole_doxygen_cmake\ .\colorconsolelib\

Добавляем примеры кода для библиотеки C++

В прошлых статьях мы написали и задокументировали библиотеку ColorConsole. Сегодня мы добавим к ней примеры использования.

Добавим папку для примеров

cd c:\projects\colorconsolelib\
mkdir examples
mkdir examples\basic
mkdir examples\color_table
mkdir examples\Russia_flag

У нас будет три примера:

- базовый, просто вывод цветной строки;

- таблица, содержащая все поддерживаемые цвета;

- флаг России.

Пример со строкой раскрашенной случайными цветами

Создадим файлы для наших примеров:

cd .\examples\basic
type nul > main.cpp 
type nul > CMakeLists.txt

Добавим код для первого примера:

code .

В файл main.cpp добавим:

#include <iostream>
#include <string>
#include <random>

#include "../../src/colorconsole.h"

using ccon::ColorConsole;

int main(int argc, char *argv[])
{
    ColorConsole::init();

    std::random_device rd;
    std::mt19937 gen(rd()); 
    std::uniform_int_distribution<> distr(0, 15);

    std::string str = "ColorConsole";

    for (int i = 0; i <= str.length()-1; i++)
    {
       ColorConsole::setConsStdOutColor(distr(gen),distr(gen));
        std::cout << str[i];       
    }   

    ColorConsole::setConsStdOutDefColor();

    return 0;
}

В файл CMakeLists.txt добавим:

cmake_minimum_required(VERSION 3.16)

project(basicexample VERSION 0.1 LANGUAGES CXX)


set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(${PROJECT_NAME}
        ..\\..\\src\\colorconsole.h 
        ..\\..\\src\\colorconsole.cpp
        main.cpp
)

include(GNUInstallDirs)

Проверим, сконфигурируем:

cmake -S . -B build

Соберем:

cmake --build build

Запустим:

.\build\basicexample.exe

При каждом запуске будет выводится строка ColorConsole, с случайным цветом букв и фона.

Скопируем проект как шаблон в другие папки:

copy CMakeLists.txt ..\color_table
copy main.cpp ..\color_table
copy CMakeLists.txt ..\Russia_flag
copy main.cpp ..\Russia_flag

Пример с таблицей всех цветов

Откроем папку color_table:

cd c:\projects\colorconsolelib\examples\color_table
code .

В файле CMakeLists.txt изменим имя проекта с:

basicexample 

на:

color_table_example

Заменим содержимое файла main.cpp на:

#include <iostream>

#include "../../src/colorconsole.h"

using ccon::ColorConsole;

int main(int argc, char *argv[])
{
    ColorConsole::init();

    ColorConsole::emptyLine(); 

    for (int i = 0; i < 256; i++)

    {
        if ((i % 16 == 0) && (i != 0)) {

            ColorConsole::emptyLine();
        }
        ColorConsole::setConsStdOutColor(i);
        printf("[%03d]",i);
    }

    ColorConsole::emptyLine();

    ColorConsole::setConsStdOutDefColor();

    return 0;
}

Проверим, сконфигурируем:

cmake -S . -B build

Соберем:

cmake --build build

Запустим:

.\build\color_table_example.exe

Будет выведена таблица со всеми цветами.

Пример с флагом России

Откроем папку Russia_flag 

cd c:\projects\colorconsolelib\examples\Russia_flag
code .

В файле CMakeLists.txt изменим имя проекта с:

basicexample 

на:

Russia_flag_example

Заменим содержимое файла main.cpp на:

#include <iostream>
#include "../../src/colorconsole.h"

using ccon::ColorConsole;

int main(int argc, char *argv[])
{
   ColorConsole::init();
   
   ColorConsole::emptyLine();
   ColorConsole::emptyLine();
   
   ColorConsole::setConsStdOutColor(ColorConsole::WHITE,ColorConsole::WHITE);
   printf("%10s"," ");   
   
   ColorConsole::emptyLine();
   
   ColorConsole::setConsStdOutColor(ColorConsole::WHITE,ColorConsole::DARK_BLUE);
   printf("%10s","  RUSSIA  ");
   
   ColorConsole::emptyLine();
   
   ColorConsole::setConsStdOutColor(ColorConsole::DARK_RED,ColorConsole::DARK_RED);
   
   printf("%10s"," ");
   ColorConsole::emptyLine();
      ColorConsole::emptyLine();
   
   ColorConsole::setConsStdOutDefColor();
   return 0;
}

Сконфигурируем:

cmake -S . -B build

Соберем:

cmake --build build

Запустим:

.\build\Russia_flag_example.exe

Будет выведен флаг России.

Добавляем target для сборки примеров использования кода (examples)

Добавим файл examples\CMakeLists.txt:

cd c:\projects\colorconsolelib\examples\
type nul > CMakeLists.txt

С содержимым:

add_subdirectory(basic)
add_subdirectory(color_table)
add_subdirectory(Russia_flag)

В данном файле мы просто указываем какие папки добавлять для сборки.

Перейдем к основному проекту:

cd c:\projects\colorconsolelib
code .

В файл targets.cmake.in перед строкой:

message(" === Targets settings complete")

Добавим:

add_subdirectory(examples EXCLUDE_FROM_ALL)

add_custom_target(examples
    DEPENDS basicexample color_table_example Russia_flag_example
)

Здесь мы указываем папку examples которая содержит файл CMakeLists.txt в котором находятся дальнейшие инструкции о том, что делать с содержимым этой папки.

Запустим конфигурирование:

cmake -S . -B build

Запустим сборку:

cmake --build build --target examples

[ 11%] Building CXX object examples/color_table/CMakeFiles/color_table_example.dir/__/__/src/colorconsole.cpp.obj
[ 22%] Building CXX object examples/color_table/CMakeFiles/color_table_example.dir/main.cpp.obj
[ 33%] Linking CXX executable color_table_example.exe
[ 33%] Built target color_table_example
[ 44%] Building CXX object examples/basic/CMakeFiles/basicexample.dir/__/__/src/colorconsole.cpp.obj
[ 55%] Building CXX object examples/basic/CMakeFiles/basicexample.dir/main.cpp.obj
[ 66%] Linking CXX executable basicexample.exe
[ 66%] Built target basicexample
[ 77%] Building CXX object examples/Russia_flag/CMakeFiles/Russia_flag_example.dir/__/__/src/colorconsole.cpp.obj
[ 88%] Building CXX object examples/Russia_flag/CMakeFiles/Russia_flag_example.dir/main.cpp.obj
[100%] Linking CXX executable Russia_flag_example.exe
[100%] Built target Russia_flag_example
[100%] Built target examples

Для сборки примеров нам обязательно нужно указать параметр:

--target examples

При сборке по умолчанию сборка примеров не происходит!

В папке .\build\

Будет создана папка examples:

└───examples
    ├───basic
    ├───color_table
    └───Russia_flag

С нашими примерами.

Мы можем запустить их после сборки:

.\build\examples\basic\basicexample.exe
.\build\examples\color_table\color_table_example.exe
.\build\examples\Russia_flag\Russia_flag_example.exe

Заключение

Сегодня мы добавили в библиотеку C++ примеры с кодом использования и собрали эти примеры с использованием CMake:

Создали папки для проектов с примерами использования;

Добавили в папки программный код и проверили работоспособность;

Добавили в проект отдельный target для сборки только кода примеров использования.