diff options
| -rw-r--r-- | doc/jenkins-cpp-build.md | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/doc/jenkins-cpp-build.md b/doc/jenkins-cpp-build.md new file mode 100644 index 0000000..31d88e2 --- /dev/null +++ b/doc/jenkins-cpp-build.md @@ -0,0 +1,173 @@ +# Building a C++ App in Jenkins (Docker Agent) + +Step-by-step guide to set up a Jenkins pipeline that builds a C++ project +using a Docker container as the build agent (DooD). + + +## 1. Push your C++ project to the git server + +On the server, create a bare repo: + +```bash +cd /var/git/repos +git init --bare my-cpp-app.git +chown -R 1000:1000 my-cpp-app.git +``` + +From your local machine, push your code: + +```bash +cd /path/to/my-cpp-app +git init +git remote add origin ssh://git@<server-ip>/repos/my-cpp-app.git +git add . +git commit -m "Initial commit" +git push -u origin master +``` + + +## 2. Add a Jenkinsfile to your project + +Create a file called `Jenkinsfile` in the root of your C++ project. + +### Simple build (g++ directly) + +```groovy +pipeline { + agent { + docker { image 'gcc:latest' } + } + + stages { + stage('Build') { + steps { + sh 'g++ -o my_app main.cpp' + } + } + + stage('Test') { + steps { + sh './my_app' + } + } + } +} +``` + +Adjust the `g++` command to match your source files. + +### CMake build + +```groovy +pipeline { + agent { + docker { image 'gcc:latest' } + } + + stages { + stage('Configure') { + steps { + sh 'cmake -B build -S .' + } + } + + stage('Build') { + steps { + sh 'cmake --build build' + } + } + + stage('Test') { + steps { + sh 'cd build && ctest --output-on-failure' + } + } + } +} +``` + +> Note: The `gcc:latest` image includes `g++`, `gcc`, `make`, and `cmake`. +> If you need extra libraries (e.g., Boost), you can use a custom image or +> add `apt-get install` steps. + +Commit and push the Jenkinsfile: + +```bash +git add Jenkinsfile +git commit -m "Add Jenkinsfile for CI" +git push +``` + + +## 3. Create the Jenkins pipeline job + +1. Open Jenkins at `https://jenkins.swave.lol` (or `https://swave.lol/jenkins`) +2. Click **New Item** (top-left) +3. Enter a name, e.g. `my-cpp-app` +4. Select **Pipeline**, then click **OK** + + +## 4. Configure the pipeline source + +On the job configuration page: + +1. Scroll down to the **Pipeline** section +2. Change **Definition** from "Pipeline script" to **Pipeline script from SCM** +3. Set **SCM** to **Git** +4. In **Repository URL**, enter: `git://git-server/my-cpp-app.git` + - This works because Jenkins and git-server are on the same `jenkins_network` (172.23.0.0/16) + - `git-server` resolves to `172.23.0.3` via Docker DNS + - The git daemon protocol (`git://`) on port 9418 requires no credentials + - Alternative: `ssh://git@git-server/repos/my-cpp-app.git` (requires SSH key setup in Jenkins) +5. Set **Branch Specifier** to `*/master` (or `*/main`, whatever your default branch is) +6. **Script Path**: leave as `Jenkinsfile` (default) +7. Click **Save** + + +## 5. Run the build + +1. On the job page, click **Build Now** (left sidebar) +2. A build number will appear under **Build History** — click it +3. Click **Console Output** to watch the build live + +You will see Jenkins: +- Pull the `gcc:latest` Docker image (first time only) +- Spin up a temporary container on the host (DooD via `/var/run/docker.sock`) +- Clone your repo inside the container +- Run each stage (`Build`, `Test`) +- Destroy the container when done + + +## 6. Automatic builds (optional) + +### Option A — Poll SCM + +1. Go to job config (**Configure**) +2. Under **Build Triggers**, check **Poll SCM** +3. Set schedule, e.g. `H/5 * * * *` (check every 5 minutes) +4. Click **Save** + +### Option B — Git post-receive hook + +Create a hook that notifies Jenkins immediately on push: + +```bash +cat > /var/git/repos/my-cpp-app.git/hooks/post-receive << 'HOOK' +#!/bin/bash +curl -s "http://jenkins:8080/jenkins/git/notifyCommit?url=git://git-server/my-cpp-app.git" > /dev/null 2>&1 & +HOOK +chmod +x /var/git/repos/my-cpp-app.git/hooks/post-receive +``` + +This requires the **Git plugin** and **Poll SCM** to be enabled in the job +config (the schedule can be empty, e.g. just `H * * * *`). + + +## How DooD works + +Jenkins is configured with Docker-out-of-Docker: it mounts the host's +`/var/run/docker.sock` into the Jenkins container. When the pipeline runs +`docker { image 'gcc:latest' }`, Jenkins creates a **sibling container** on +the host (not nested), runs the build steps inside it, and removes it after. +The Jenkins container never needs compilers installed — everything runs in the +ephemeral `gcc` container. |