Code/cplusplus/geminitutorial/tutorial1/tutorial-part1-1.md

Tutorial 1.1: Your First Modern C++ Project

Objective: To compile, run, debug, and manage dependencies for a C++ application using the modern, industry-standard toolchain on Linux. This single tutorial covers the entire end-to-end workflow.

---

1. Prerequisites: System Setup

First, you need to ensure the necessary base tools are installed. Open your terminal and run the following commands.

# Update package lists
sudo apt update

# Install compiler (g++), make, git, and other essential build tools
sudo apt install build-essential g++ git cmake curl

You will also need Visual Studio Code, which you can download from the official website.

After installing VSCode, launch it and install these two essential extensions from the Extensions view (Ctrl+Shift+X):

1. C/C++ (Publisher: Microsoft)
2. CMake Tools (Publisher: Microsoft)

2. The Game Changer: vcpkg Package Manager

In C++ circa 2000, adding a library was a manual ordeal. vcpkg automates this. It downloads, builds, and prepares libraries for your project, acting like pip for Python.

In your terminal, choose a location for your development tools (e.g., ~/dev/tools) and clone vcpkg:

# Create a directory for tools if you don't have one
mkdir -p ~/dev/tools
cd ~/dev/tools

# Clone the vcpkg repository
git clone https://github.com/microsoft/vcpkg.git

# Run the bootstrap script to build vcpkg itself
./vcpkg/bootstrap-vcpkg.sh

IMPORTANT: Note the absolute path to your vcpkg installation. You'll need it later. It will be something like /home/YOUR_USERNAME/dev/tools/vcpkg.

3. Project Setup

Now, let's create the project.

# Go to where you keep your code projects
cd ~/code/cplusplus/GeminiTutorial

# Create and enter the project directory
mkdir tutorial-1
cd tutorial-1

4. Installing a Library

Let's install spdlog, a popular and high-performance logging library.

# Use the vcpkg executable to install the library
# Replace /path/to/vcpkg with your actual vcpkg path
/home/YOUR_USERNAME/dev/tools/vcpkg/vcpkg install spdlog

This command will download, compile, and install spdlog into your vcpkg directory, making it available for any project.

5. Writing the Build Script (CMakeLists.txt)

This file tells CMake how to build your project. Create a file named CMakeLists.txt inside the tutorial-1 directory with the following content.

# Specifies the minimum version of CMake required.
cmake_minimum_required(VERSION 3.15)

# Defines the project name and sets C++ as the language.
project(Tutorial1 LANGUAGES CXX)

# Set the C++ standard to C++17. Modern C++ starts with C++11.
# C++17 is a great, stable choice.
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Find the spdlog library.
# CMake needs to be told how to find packages installed by vcpkg.
# We will do this in the VSCode settings in the next step.
# 'CONFIG REQUIRED' means it's a fatal error if the package isn't found.
find_package(spdlog CONFIG REQUIRED)

# Define our executable target, named 'App', from the source file 'main.cpp'.
add_executable(App main.cpp)

# Link our App against the spdlog library.
# This tells the compiler to include the necessary spdlog files when building App.
target_link_libraries(App PRIVATE spdlog::spdlog)

6. Writing the C++ Code (main.cpp)

Create a file named main.cpp in the tutorial-1 directory.

#include <iostream>

// Include the main header from the spdlog library.
#include "spdlog/spdlog.h"

int main() {
    // Use the library to print an informational message.
    // This is much more powerful than std::cout for real applications,
    // as it can be configured to log to files, rotate logs, filter by level, etc.
    spdlog::info("Hello, Modern C++! Initializing trading strategy...");

    int x = 42;
    double price = 102.5;

    // spdlog supports formatted output similar to Python's f-strings.
    spdlog::warn("A variable 'x' has value: {}", x);
    spdlog::critical("Critical event! Price is: {}", price);

    std::cout << "Check your terminal for spdlog output!" << std::endl;

    return 0;
}

7. Building and Debugging in VSCode

This is where all the pieces come together.

1. Open the Project: Launch VSCode and open the tutorial-1 folder (File > Open Folder...).

2. Configure CMake:

   • The CMake Tools extension will activate. You may see a prompt asking to configure the project.
   • This will fail initially! This is expected. An error will appear saying Could not find a package configuration file for "spdlog".
   • Here is the fix: We must tell CMake where to find vcpkg-installed libraries.
   • Open the VSCode settings: File > Preferences > Settings (or Ctrl+,).
   • Click the "Workspace" tab. Search for cmake.configureArgs.
   • Click "Edit in settings.json".
   • Add the following entry, replacing the path with the actual absolute path to your vcpkg directory:

   {
       "cmake.configureArgs": [
           "-DCMAKE_TOOLCHAIN_FILE=/home/YOUR_USERNAME/dev/tools/vcpkg/scripts/buildsystems/vcpkg.cmake"
       ]
   }
   

   • Save settings.json. A new .vscode directory will be created in your project folder to store this setting.

3. Build the Project:

   • Run the CMake: Configure command from the command palette (Ctrl+Shift+P). It should now succeed.
   • The status bar at the bottom of VSCode now shows buttons for building. Click the Build button.
   • You'll see output in the terminal as CMake and the compiler build your App executable.

4. Run and Debug:

   • Run: The "play" button in the status bar will run the executable. You'll see the spdlog output in the VSCode terminal.
   • Debug:
     1. Open main.cpp.
     2. Click in the gutter to the left of the line number for int x = 42; to set a breakpoint (a red dot will appear).
     3. Press F5 (or click the "bug" icon next to the play button).
     4. Execution will start and then stop at your breakpoint.
     5. You can now inspect variables in the "Run and Debug" side panel and use the controls to step through the code (F10, F11).

---

Congratulations! You have successfully set up a modern C++ development environment, managed an external dependency, and used the integrated build/debug tools. This workflow is the foundation for all subsequent tutorials.

8 Feedback

There is a dependency on gdb debugger that was not mentioned. after building and installing everything works as expected