Ciux Documentation
Table of Contents
1. Introduction
Overview
Ciux is a versatile tool designed to automate build processes and streamline integration testing. This documentation provides guidance on installing, configuring, and utilizing Ciux in your development workflows.
Key Features
-
Build Automation: Ciux automates the build process, ensuring consistency and reliability in source code dependencies generating software artifacts.
-
Integration Testing: Facilitates seamless integration testing with support for various dependencies and configurations.
2. Getting Started
Installation
To install Ciux, use the following command:
$ go install github.com/k8s-school/ciux@<version>
Configuration
Ciux requires a configuration file (.ciux
) at the top level of your source code repository. Example configuration:
apiVersion: v1alpha1
registry: gitlab-registry.in2p3.fr/astrolabsoftware/fink
dependencies:
- url: https://github.com/astrolabsoftware/fink-alert-simulator
clone: true
pull: true
labels:
itest: "true"
ci: "true"
- url: https://github.com/astrolabsoftware/finkctl
clone: true
labels:
itest: "true"
ci: "true"
- image: gitlab-registry.in2p3.fr/astrolabsoftware/fink/spark-py:k8s-3.4.1
labels:
build: "true"
- package: github.com/k8s-school/ktbx@v1.1.1-rc7
labels:
itest: "optional"
ci: "true"
3. Usage
Prerequisites
- Defining the
CIUXCONFIG
Variable
Before using Ciux, the CIUXCONFIG
variable must be defined.
$ export CIUXCONFIG="$HOME/.ciux/ciux.sh"
- The
CIUXCONFIG
variable is utilized by Ciux to dynamically retrieve source code and version information during the build and integration testing processes.
Building a project with ciux:
- Prepare the build process by generating the
CIUXCONFIG
file, usingciux ignite
:
$ cd <project-source-directory>
$ ciux ignite --selector build
- Example
CIUXCONFIG
content:
export FINK_BROKER_DIR=/home/fjammes/src/astrolabsoftware/fink-broker
export FINK_BROKER_VERSION=v3.1.1-rc1-7-ga4bf010
export ASTROLABSOFTWARE_FINK_SPARK_PY_IMAGE=gitlab-registry.in2p3.fr/astrolabsoftware/fink/spark-py:k8s-3.4.1
-
Explanation:
-
The
ciux ignite
command orchestrates the following crucial steps:-
Dependency Selection: This phase involves dynamic selection of dependencies based on specified labels such as
build
. Ciux identifies and includes only those dependencies that are relevant to the current workflow. -
Image Existence Check: Ciux ensures the availability of images in the remote registry associated with the specified dependencies. This verification step guarantees that the required images are present and accessible before initiating subsequent processes.
-
Git Cloning Process:
- For each selected dependency, Ciux performs a Git clone operation, fetching the source code from the respective repositories. The cloning process use the very same branch of the main project. If the specified branch does not exist if a dependency, Ciux defaults to
main
ormaster
.
- For each selected dependency, Ciux performs a Git clone operation, fetching the source code from the respective repositories. The cloning process use the very same branch of the main project. If the specified branch does not exist if a dependency, Ciux defaults to
-
Go Package Installation: Additionally, during the ignite process, Ciux installs Go packages that are essential for the project and its dependencies. This ensures that the required Go packages are available and compatible with the project's build and integration testing.
-
-
The generated
CIUXCONFIG
variable encapsulates the dynamically determined information about source code locations, versions, and package installations. This variable is crucial for Ciux to maintain a consistent and reproducible development environment during subsequent build and integration processes. -
Utilizing the
CIUXCONFIG
variable, Ciux facilitates a streamlined workflow, automating the setup of dependencies and environment configurations essential for successful integration testing and continuous integration.
-
-
Build the project
To build the project using Ciux, a two-step process is required. It involves sourcing the CIUXCONFIG
file, which sets essential environment variables, and subsequently running the project's build script that relies on these environment variables.
-
Source
CIUXCONFIG
to Set Environment Variables:-
Prior to initiating the build process, source the
CIUXCONFIG
file to set the necessary environment variables. This file contains crucial information about the project's dependencies, source code locations, and version details.$ source $CIUXCONFIG
-
Sourcing
CIUXCONFIG
ensures that the environment variables required for the build process are properly configured and accessible.
-
-
Run the Build Script of the Project:
-
With the environment variables set by sourcing
CIUXCONFIG
, execute the build script of the project. This script is responsible for compiling, assembling, and generating the project artifacts.$ <project-source-directory>/path/to/build/script.sh
-
The build script should be designed to utilize the environment variables set by Ciux, such as source code locations, version details, and any other configurations specified in the
CIUXCONFIG
file.
-
Integration Tests
- Prepare integration tests by generating the
CIUXCONFIG
file, usingciux ignite
with dedicated labels:
$ cd <source-directory>
$ ciux ignite --selector ci
- Example
CIUXCONFIG
content:
export FINK_ALERT_SIMULATOR_DIR=/home/fjammes/src/astrolabsoftware/fink-alert-simulator
export FINK_ALERT_SIMULATOR_VERSION=v3.1.1-rc1
export FINKCTL_DIR=/home/fjammes/src/astrolabsoftware/finkctl
export FINKCTL_VERSION=v3.1.1-rc2-2-g68a1d41
export FINK_BROKER_DIR=/home/fjammes/src/astrolabsoftware/fink-broker
export FINK_BROKER_VERSION=v3.1.1-rc1-7-ga4bf010
- Run integration tests
$ source $CIUXCONFIG
<project-source-directory>/path/to/integration-test/script.sh