Flujos de trabajo

Al ejecutar nbuild:

nbuild -n network.json -w workflow.json -s secrets.json

El segundo parámetro workflow.json contiene la configuración del flujo de trabajo.

1. Empaquetado del código

La primera tarea que se llevará a cabo en un flujo de nbuild será la selección, pre-proceso y empaquetado del código fuente (Figura 1). Es posible que cierto flujo solo necesite procesar unos pocos targets para generar el producto final, obviando el resto del repositorio. En este contexto denominamos target a una colección de archivos fuente que generan una librería o un ejecutable. En proyectos u organizaciones grandes, un repositorio puede contener infinidad de targets inter-dependientes, que sirvan de base para construir diferentes flujos con los que gestionar diferentes líneas de producción. Por otro lado, durante este pre-procesado se podrán ejecutar herramientas de análisis estático (cpp-check) o de formateo de código (clang-format). Esto dará cohesión a todos los archivos, independientemente de quien o como se hayan editado. También se editarán automáticamente los archivos fuente, incluyendo cabeceras con la información legal del proyecto. Recordamos que para nbuild, el código fuente es un artefacto más, pudiendo formar parte del producto final. Esta fase dejará todos los fuentes listos para ser publicados en GitHub o cualquier otra plataforma de distribución.

2. workflow.json

En (Listado 1) tenemos el ejemplo de un flujo de trabajo en formato Json. El objeto global contendrá los parámetros de configuración y targets, por su parte, el array de librerías/ejecutables necesarios para completar el flujo.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

{
"global" : {
    "project" :  "NAppGUI",
    "description" : "Cross-platform C SDK",
    "start_year" : 2015,
    "author" : "Francisco Garcia Collado",
    "license" : [
        "MIT Licence",
        "https://nappgui.com/en/legal/license.html" ],

    "flowid" : "nappgui_dev",

    "repo_url" : "svn://192.168.1.2/svn/NAPPGUI",
    "repo_branch" : "trunk",
    "repo_user" : $SECRET{repo_user},
    "repo_pass" : $SECRET{repo_pass},

    "doc_repo_url" : "svn://192.168.1.2/svn/NAPPGUI/nbuild/doc",
    "doc_repo_user" : $SECRET{repo_user},
    "doc_repo_pass" : $SECRET{repo_pass},
    "doc_url" : "https://nappgui.com",
    "doc_deflang" : "en",

    "hosting_url" : $SECRET{hosting_url},
    "hosting_user" : $SECRET{hosting_user},
    "hosting_pass" : $SECRET{hosting_pass},
    "hosting_cert" : false,
    "hosting_docpath" : "./web/docs",
    "hosting_buildpath" : "./web/builds"
    },

"targets" : [
    {"name" : "src/sewer", "legal" : true, "format" : true, "analyzer" : true },
    {"name" : "src/gui", "legal" : true, "format" : true, "analyzer" : true },
    ...
    {"name" : "demo/dice", "legal" : false, "format" : true, "group" : "NAPPGUI_DEMO" },
    ...
    ],

"paths" : [
    { "name" : "prj" },
    { "name" : "src/nappgui.h" },
    { "name" : "Changelog.md" },
    { "name" : "README.md" },
    { "name" : "LICENSE" }
    ],

"makefile" : "CMakeLists.txt",
"version" : "prj/version.txt",
"build" : "prj/build.txt",
"clang_format" : ".clang-format"
}

3. Globales

Los campos a incluir en el objeto globals son:

Datos básicos (obligatorios):

• project: Nombre del proyecto.
• description: Descripción breve del proyecto (40-80 caracteres).
• start_year: Año de comienzo del proyecto.
• author: Autor.
• license: Array de textos con información sobre la licencia.
• flowid: Identificador del flujo. nbuild puede correr varias instancias en paralelo, siempre que trabajen en flujos diferentes. También se utiliza para crear los directorios principales de almacenamiento en el nodo drive drive::path::flowid.

Datos del repositorio (obligatorios):

• repo_url: Url del repositorio. Por el momento solo se soporta Subversion.
• repo_branch: Rama del repositorio donde descargaremos el código.
• repo_user: Usuario del repositorio.
• repo_pass: Contraseña del repositorio.

Documentación del proyecto (opcional): Si el proyecto dispone de documentación en formato ndoc y queremos generarla, debemos de aportar la siguiente información:

• doc_repo_url: Url del repositorio que contiene la documentación. Por el momento solo se soporta Subversion.
• doc_repo_user: Usuario del repositorio de documentación.
• doc_repo_pass: Contraseña del repositorio de documentación.
• doc_url: Url del sitio donde se publica la documentación. Si se omite, se considera que no existe un sitio público y la documentación se distribuye empaquetada.
• doc_deflang: Idioma por defecto en portal público de documentación. ndoc soporta documentos en varios lenguajes.

Datos del hosting web (opcional): Tanto la documentación del proyecto generada por ndoc, como los reportes del resultado de cada sesión son almacenados en el nodo drive (ver Gestión de artefactos en drive). Si queremos publicarla en algún servidor Web con el fin de tenerla más accesible, deberemos aportar los datos del hosting donde se alojarán dichas páginas y recursos.

• hosting_url: Url de acceso al hosting.
• hosting_user: Usuario del del hosting.
• hosting_pass: Contraseña del hosting.
• hosting_cert: true si el hosting utiliza el certificado RSA del nodo master.
• hosting_docpath: Path dentro del hosting donde se aloja la documentación del proyecto.
• hosting_buildpath: Path dentro del hosting donde se alojan los reportes de nbuild.

4. Targets

Una vez establecida la configuración general del proyecto, vamos a definir los targets que vamos a incluir dentro del flujo. Recordamos que un target es un proyecto de compilación que genera un artefacto binario (una librería o un ejecutable). En workflow.json, en el array target deberemos proporcionar estos campos para cada entrada:

• name: Ruta de la carpeta principal del target, a partir de la raíz del repositorio.
• legal: true si queremos añadir información legal o de autoría en cada archivo fuente del target.
• format: true si queremos aplicar formateo de código (clang-format) a cada archivo fuente del target.
• analyzer: true si queremos ejecutar el analizador estático (cpp-check) en cada archivo fuente del target.
• group: Grupo al que pertenece el target (opcional). Ver CMakeLists.txt.

Si hemos seleccionado true en el campo format, se añadirá esta información como cabecera de cada archivo fuente del target, generada a partir de los datos del proyecto.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

/*
 * NAppGUI Cross-platform C SDK
 * 2015-2024 Francisco Garcia Collado
 * MIT Licence
 * https://nappgui.com/en/legal/license.html
 *
 * File: button.h
 * https://nappgui.com/en/gui/button.html
 *
 */

Para cabeceras .h, .hpp o .hxx, si hemos configurado una url pública para la documentación (doc_url), se incluirá un enlace en el archivo fuente a la página de documentación.

5. Otros archivos

La entrada paths del workflow.json indica archivos o directorios del repositorio original que deben ser empaquetados junto con el código fuente (configuración, recursos, etc). Por lo general, son archivos necesarios para que el proyecto compile, sin ser código fuente. Se realizará una copia directa, sin procesar, desde el repositorio al paquete generado.

• name: Ruta del archivo o directorio, a partir de la raíz del repositorio a copiar en el empaquetado.

6. CMakeLists.txt

La entrada makefile de workflow.json indica la ruta dentro del repositorio al archivo CMakeLists.txt necesario para compilar el flujo. Este archivo será instalado en la carpeta principal del empaquetado. Debemos asegurar que cumple estos dos requisitos:

• Instalación: Debe incluir los comandos install() necesarios para realizar una correcta instalación del proyecto al ejecutar el comando cmake --install. Como veremos posteriormente, nbuild instala el proyecto una vez compilado en cualquier nodo host, antes de lanzar cualquier tarea de ejecución o testing.
• Soportar lista de targets: nbuild creará un archivo CMakeTargets.cmake (Listado 2) con aquellas entradas incluidas en el array targets de workflow.json. Por tanto, el CMakeLists.txt debe hacer referencia a este archivo, evitando llamar directamente a add_subdirectory() (Listado 3). Si hemos indicado algún group al definir el target, su generación estará condiciona a una option de CMake (por ejemplo, NAPPGUI_DEMO).

1 2 3 4 5 6 7 8 9

<c>CMakeTargets.cmake</c>. # CMakeTargets.cmake automatic generated by nbuild set(ALL_TARGETS "") set(ALL_TARGETS ${ALL_TARGETS};src/sewer;src/osbs;...;src/gui) if (NAPPGUI_DEMO) set(ALL_TARGETS ${ALL_TARGETS};demo/dice;...) endif()

1 2 3 4 5 6 7

... # Generate targets include(${NAPPGUI_ROOT_PATH}/CMakeTargets.cmake) foreach (target ${ALL_TARGETS}) add_subdirectory(${target}) endforeach() ...

7. Datos adicionales

Por último, estas entradas son opcionales dentro del workflow.json pero se recomienda incluirlas.

• version: Archivo dentro del repositorio que indica la versión del flujo. Tan solo debe incluir una línea con el formato major.minor.path (1.5.6).
• build: Ruta dentro del empaquetado final que contendrá la versión del repositorio con la que se ha generado el flujo.
• clang_format: Ruta dentro del repositorio al archivo .clang-format con el que dar formato a los archivos fuentes. Diferentes flujos pueden utilizar diferentes formatos para el mismo código fuente.

8. Gestión de artefactos en drive

En esta sección se detalla la estructura de archivos y directorios en la nodo drive.