# Table of Contents
- [About](#about)
- [Prerequisite](#prerequisite)
- [Tools](#tools)
- [Third party tools](#third-party-tools)
- [Installation](#installation)
- [Download from dockerhub](#download-from-dockerhub)
- [Build from chiselapp (fossil)](#build-from-chiselapp--fossil-)
- [Build from github](#build-from-github)
- [Configuration](#configuration)
- [Build arguments](#build-arguments)
- [Example of build](#example-of-build)
- [Configuration options](#configuration-options)
- [General options](#general-options)
- [Timezone](#timezone)
- [Applications](#applications)
- [Configuration](#configuration)
- [Usage](#usage)
- [Builder](#builder)
- [Build applications](#build-applications)
- [Prepare source packages](#prepare-source-packages)
- [Continues Integration](#continues-integration)
- [Maintenance](#maintenance)
- [Log output](#log-output)
- [Shell access](#shell-access)
<a id="about"></a>
# About
This is [ubuntu base docker image](https://hub.docker.com/_/ubuntu) (version 22.04) using [s6-overlay](https://github.com/just-containers/s6-overlay) for buid tcl software. The basic idea was taken from [tcl2020-build](https://github.com/tcl2020/tcl2020-build) .
Tcl-build is self-hosting at <https://chiselapp.com/user/oupfiz5/repository/tcl-build>.
If you are reading this on GitHub, then you are looking at a Git mirror of the self-hosting tcl-build repository. The purpose of that mirror is to test and exercise Fossil's ability to export a Git mirror and using Github CI/CD (Github Actions). Nobody much uses the GitHub mirror, except to verify that the mirror logic works. If you want to know more about tcl-build, visit the official self-hosting site linked above.
<a id="prerequisite"></a>
# Prerequisite
<a id="tools"></a>
## Tools
1. \*nix operation system
2. Install Docker
3. Install git (optional)
4. Install fossil (optional)
<a id="third-party-tools"></a>
## Third party tools
They are using for testing and scanning:
1. [BATS](https://github.com/bats-core)
2. [Shellcheck](https://github.com/koalaman/shellcheck/)
3. [Hadolynt](https://github.com/hadolint/hadolint)
4. [Dockle](https://github.com/goodwithtech/dockle)
5. Snyk (todo)
6. Trivy (todo)
<a id="installation"></a>
# Installation
<a id="download-from-dockerhub"></a>
## Download from dockerhub
docker pull oupfiz5/tcl-build:latest
docker pull oupfiz5/tcl-build:23.05
<a id="build-from-chiselapp--fossil-"></a>
## Build from chiselapp (fossil)
fossil clone https://chiselapp.com/user/oupfiz5/repository/tcl-build tcl-build.fossil
mkdir tcl-build
cd tcl-build
fossil open ../tcl-build.fossil
docker build -t oupfiz5/tcl-build .
<a id="build-from-github"></a>
## Build from github
git clone https://github.com/oupfiz5/tcl-build.git
cd tcl-build
docker build -t oupfiz5/tcl-build .
<a id="configuration"></a>
## Configuration
<a id="build-arguments"></a>
### Build arguments
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
<col class="org-left" />
<col class="org-left" />
<col class="org-left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="org-left">Arguments</th>
<th scope="col" class="org-left">Default</th>
<th scope="col" class="org-left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="org-left">BUILD_DATE</td>
<td class="org-left">none</td>
<td class="org-left">Set build date for label</td>
</tr>
</tbody>
<tbody>
<tr>
<td class="org-left">FOSSIL_VERSION</td>
<td class="org-left">2.21</td>
<td class="org-left">Set upload fossil version</td>
</tr>
</tbody>
<tbody>
<tr>
<td class="org-left">VERSION</td>
<td class="org-left">none</td>
<td class="org-left">Set version for label</td>
</tr>
</tbody>
</table>
<a id="example-of-build"></a>
### Example of build
docker build \
--build-arg BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
--build-arg VERSION='23.05' \
--build-arg FOSSIL_VERSION='2.21' \
--tag oupfiz5/tcl-build:23.05 \
--file ./Dockerfile \
.
<a id="configuration-options"></a>
# Configuration options
For configuration is using environment variables.
<a id="general-options"></a>
## General options
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
<col class="org-left" />
<col class="org-left" />
<col class="org-left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="org-left">Option</th>
<th scope="col" class="org-left">Default</th>
<th scope="col" class="org-left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="org-left">TZ</td>
<td class="org-left">UTC</td>
<td class="org-left">Set timezone, example Europe/Moscow</td>
</tr>
</tbody>
</table>
<a id="timezone"></a>
## Timezone
Set the timezone for the container, defaults to UTC. To set the timezone set the desired timezone with the variable TZ.
mkdir -p $(pwd)/workspaces
docker run -itd \
-v $(pwd)/workspaces:/workspaces\
-v $(pwd)/builds:/builds \
--env 'TZ=Europe/Moscow' \
--name=tcl-build \
oupfiz5/tcl-build:23.05
<a id="applications"></a>
# Applications
The docker support builds for the following applications:
- tcl
- tcllib
- rl\_json
- NaviServer (modules)
- tDOM
- xotcl
<a id="configuration"></a>
## Configuration
For configuration is using docker environment variable and/or `builds/env-vars.sh`
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
<col class="org-left" />
<col class="org-right" />
<col class="org-left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="org-left">Option</th>
<th scope="col" class="org-right">Default</th>
<th scope="col" class="org-left">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="org-left">PREFIX</td>
<td class="org-right">/usr</td>
<td class="org-left">Default values for prefix</td>
</tr>
</tbody>
<tbody>
<tr>
<td class="org-left">NS_VERSION</td>
<td class="org-right">4.99.24</td>
<td class="org-left">Define NaviServer version</td>
</tr>
</tbody>
<tbody>
<tr>
<td class="org-left">NS_MODULES_VERSION</td>
<td class="org-right">4.99.24</td>
<td class="org-left">Define NaviServer modules version</td>
</tr>
</tbody>
<tbody>
<tr>
<td class="org-left">RL_JSON_VERSION</td>
<td class="org-right">0.12.2</td>
<td class="org-left">Define <a href="https://github.com/RubyLane/rl_json">RL_JSON</a> version</td>
</tr>
</tbody>
<tbody>
<tr>
<td class="org-left">TCL_VERSION</td>
<td class="org-right">8.6.13</td>
<td class="org-left">Define tcl version</td>
</tr>
</tbody>
<tbody>
<tr>
<td class="org-left">TCLLIB_VERSION</td>
<td class="org-right">1.20</td>
<td class="org-left">Define tcl lib version</td>
</tr>
</tbody>
<tbody>
<tr>
<td class="org-left">TDOM_VERSION</td>
<td class="org-right">0.9.1</td>
<td class="org-left">Define tdom version</td>
</tr>
</tbody>
<tbody>
<tr>
<td class="org-left">XOTCL_VERSION</td>
<td class="org-right">2.4.0</td>
<td class="org-left">Define xotcl version</td>
</tr>
</tbody>
</table>
<a id="usage"></a>
# Usage
<a id="builder"></a>
## Builder
Run the build container in the background with Docker:
mkdir -p $(pwd)/workspaces
docker run -itd \
-v $(pwd)/workspaces:/workspaces \
-v $(pwd)/builds:/builds \
--name=tcl-build \
oupfiz5/tcl-build:23.05
<a id="build-applications"></a>
## Build applications
Build all program in tcl-build using a `docker exec` and default congratulations:
docker exec -it tcl-build bash /builds/all-build.sh
Build any applications with version customization in tcl-build using `docker exec`. For example install tcl version 8.6.11 is:
docker exec -it \
-e TCL_VERSION=8.6.13 \
tcl-build \
bash /builds/tcl-build.sh
Modify the source code of any package in the workspaces directory. Then you can use make, cmake, … to rebuild the container with the changes. Use the build container with your favorite IDE.
<a id="prepare-source-packages"></a>
# Prepare source packages
Source packages are added to the Docker image using the `builds/build-all.sh` script.
To add packages or features create a two shell scripts in `builds` directory. One shell script will download the source package: `yourpackage-download.sh`. The other script will build the package: `yourpackage-build.sh`. Add your new build script, `yourpackage-build.sh`, to `builds/all-build.sh`.
<a id="continues-integration"></a>
# Continues Integration
For build and push docker images using [Github Actions workflow](https://github.com/oupfiz5/build-tcl/blob/master/.github/workflows/on-push.yaml). Flow process is [GitHub flow](https://guides.github.com/introduction/flow/).
<a id="maintenance"></a>
# Maintenance
<a id="log-output"></a>
## Log output
For debugging and maintenance purposes you may want access the output log. If you are using Docker version 1.3.0 or higher you can access a running containers shell by starting bash using docker interactive:
docker run -it --rm \
--name=tcl-build \
oupfiz5/tcl-build:latest \
/bin/bash
<a id="shell-access"></a>
## Shell access
For debugging and maintenance purposes you may want access the containers shell. If you are usingDocker version 1.3.0 or higher you can access a running containers shell by starting bash using docker exec:
docker exec -it tcl-build /bin/bash