Prepare v5.3.0

CHANGELOG.rst

@@ -1,6 +1,12 @@
 lib_mic_array change log
 ========================
 
+UNRELEASED
+----------
+
+  * FIXED:   Vanilla configuration now compiles correctly under XTC 15.3.0
+  * ADDED:   Support for XCommon CMake build system
+
 5.2.0
 -----
 
@@ -215,4 +221,3 @@ lib_mic_array change log
     - lib_logging: Added dependency 2.0.0
 
     - lib_xassert: Added dependency 2.0.0
-

Jenkinsfile

@@ -23,45 +23,74 @@ pipeline {
         REPO = 'lib_mic_array'
     }
     stages {
-        stage('Basic tests') {
-            agent {
-                label 'x86_64 && linux'
-            }
-            stages {
-                stage("Setup") {
-                    // Clone and install build dependencies
+        stage('Build and Docs') {
+            parallel {
+                stage('Build Docs') {
+                    agent { label "docker" }
+                    environment { XMOSDOC_VERSION = "v4.0" }
                     steps {
-                        // Print the build agent name
-                        println "RUNNING ON"
-                        println env.NODE_NAME
-                        // Clone infrastructure repos
-                        sh "git clone --branch v1.4.6 [email protected]:xmos/infr_apps"
-                        sh "git clone --branch v1.2.1 [email protected]:xmos/infr_scripts_py"
-                        // clone
-                        dir("$REPO") {
-                            checkout scm
-                            sh "git submodule update --init --recursive"
-                            withTools(params.TOOLS_VERSION) {
-                                installDependencies()
-                            }
+                        checkout scm
+                        sh 'git submodule update --init --recursive --depth 1'
+                        sh "docker pull ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION"
+                        sh """docker run -u "\$(id -u):\$(id -g)" \
+                            --rm \
+                            -v ${WORKSPACE}:/build \
+                            ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION -v"""
+                        archiveArtifacts artifacts: "doc/_build/**", allowEmptyArchive: true
+                    }
+                    post {
+                        cleanup {
+                            xcoreCleanSandbox()
                         }
                     }
                 }
-                stage("Lib checks") {
-                    steps {
-                        println "Unlikely these will pass.."
-                        // warnError("Source Check"){ sourceCheck("${REPO}") }
-                        // warnError("Changelog Check"){ xcoreChangelogCheck("${REPO}") }
+                stage('Basic tests') {
+                    when {
+                        expression { !env.GH_LABEL_DOC_ONLY.toBoolean() }
+                    }
+                    agent {
+                        label 'x86_64 && linux'
+                    }
+                    stages {
+                        stage("Setup") {
+                            // Clone and install build dependencies
+                            steps {
+                                // Print the build agent name
+                                println "RUNNING ON"
+                                println env.NODE_NAME
+                                // Clone infrastructure repos
+                                sh "git clone --branch v1.4.6 [email protected]:xmos/infr_apps"
+                                sh "git clone --branch v1.2.1 [email protected]:xmos/infr_scripts_py"
+                                // clone
+                                dir("$REPO") {
+                                    checkout scm
+                                    sh "git submodule update --init --recursive"
+                                    withTools(params.TOOLS_VERSION) {
+                                        installDependencies()
+                                    }
+                                }
+                            }
+                        }
+                        stage("Lib checks") {
+                            steps {
+                                println "Unlikely these will pass.."
+                                // warnError("Source Check"){ sourceCheck("${REPO}") }
+                                // warnError("Changelog Check"){ xcoreChangelogCheck("${REPO}") }
+                            }
+                        }
+                    }
+                    post {
+                        cleanup {
+                            xcoreCleanSandbox()
+                        }
                     }
-                }
-            }
-            post {
-                cleanup {
-                    xcoreCleanSandbox()
                 }
             }
         }
         stage('HW tests') {
+            when {
+                expression { !env.GH_LABEL_DOC_ONLY.toBoolean() }
+            }
             agent {
                 label 'xvf3800' // We have plenty of these (6) and they have a single XTAG connected
             }
@@ -115,4 +144,4 @@ pipeline {
             }
         }
     }
-}
+}

doc/README.rst

@@ -1,33 +1,19 @@
-######################
-Building Documentation
-######################
-
-Instructions are given below to build the documentation.  The recommended method is using Docker, 
-however, alternative instructions are provided in case using Docker in not an option.
-
-To develop the content of this repository, it is recommended to launch a `sphinx-autobuild`
-server as per the instructions below. Once started, point a web-browser at
-http://127.0.0.1:8000. If running the server within a VM, remember to configure
-port forwarding.
+####################
+Documentation Source
+####################
 
-You can now edit the .rst documentation, and your web-browser content will automatically
-update.
+This folder contains source files for the documentation. The sources do not render well in GitHub or an RST viewer.
+In addition, some information is not visible at all and some links will not be functional.
 
-************
-Using Docker
-************
+**********************
+Building Documentation
+**********************
 
 =============
 Prerequisites
 =============
 
-Install `Docker <https://www.docker.com/>`_.
-
-Pull the docker container:
-
-.. code-block:: console
-
-    $ docker pull ghcr.io/xmos/doc_builder:main
+Use the `xmosdoc tool <https://github.com/xmos/xmosdoc>`_ either via docker or install it into a pip environment.
 
 ========
 Building
@@ -37,48 +23,41 @@ To build the documentation, run the following command in the root of the reposit
 
 .. code-block:: console
 
-    $ docker run --rm -t -u "$(id -u):$(id -g)" -v $(pwd):/build -e REPO:/build -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc ghcr.io/xmos/doc_builder:main
+    # via pip package
+    xmosdoc clean html latex
+    # via docker
+    $ docker run --rm -t -u "$(id -u):$(id -g)" -v $(pwd):/build ghcr.io/xmos/xmosdoc clean html latex
 
-********************
-Without Using Docker
-********************
+HTML document output is saved in the ``doc/_build/html`` folder.  Open ``index.html`` to preview the saved documentation.
 
-=============
-Prerequisites
-=============
+Please refer to the ``xmosdoc`` documentation for a complete guide on how to use the tool.
 
-Install `Doxygen <https://www.doxygen.nl/index.html>`_.
+**********************
+Adding a New Component
+**********************
 
-Install the required Python packages:
+Follow the following steps to add a new component.
 
-.. code-block:: console
+- Add an entry for the new component's top-level document to the appropriate TOC in the documents tree.
+- If the new component uses `Doxygen`, append the appropriate path(s) to the INPUT variable in `Doxyfile.inc`.
+- If the new component includes `.rst` files that should **not** be part of the documentation build, append the appropriate pattern(s) to `exclude_patterns.inc`.
 
-    $ pip install -r requirements.txt
+***
+FAQ
+***
 
-========
-Building
-========
+Q: Is it possible to build just a subset of the documentation?
 
-Build documentation:
+A: Yes, however it is not recommended at this time.
 
-.. code-block:: console
-
-    $ make html
+Q: Is it possible to used the ``livehtml`` feature of Sphinx?
 
-Launch sphinx-autobuild server:
+A: Yes, run xmosdoc with the ``--auto`` option.
 
-.. code-block:: console
+Q: Where can I learn more about the XMOS ``xmosdoc`` tools?
 
-    $ make livehtml
+A: See the https://github.com/xmos/xmosdoc repository.  See the ``xmosdoc`` repository README for details on additional build options.
 
-Clean documentation:
+Q: How do I suggest enhancements to the XMOS ``xmosdoc`` tool?
 
-.. code-block:: console
-
-    $ make clean
-
-Clean and build documentation with link check:
-
-.. code-block:: console
-
-    $ make clean html linkcheck SPHINXOPTS="-W --keep-going"
+A: Create a new issue here: https://github.com/xmos/xmosdoc/issues

doc/doc_excludes.txt → doc/exclude_patterns.inc

@@ -1,3 +1,5 @@
 /build/*build*/**/*.rst
 /build/*build*/**/*.md
-**/disclaimer.rst
+CHANGELOG.rst
+LICENSE.rst
+**README* 

doc/programming_guide/src/decimator_stages.rst

@@ -277,7 +277,7 @@ overall combined response provides a nice flat passband.
 .. image:: 32k_freq_response.png
 
 Filter Characteristics for `good_48k_filter_int.pkl`
-''''''''''''''''''''''''''''''''''''''''''''''''''
+''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 The plot below indicates the frequency response of the first and second stages of the 
 provided 48 kHz filters as well as the cascaded overall response. Note that the 

doc/programming_guide/src/getting_started.rst

@@ -1,4 +1,4 @@
-.. _getting_started:
+.. _mic_array_getting_started:
 
 Getting Started
 ===============

etc/vanilla/mic_array_vanilla.cpp

@@ -5,6 +5,8 @@
 #include <xcore/channel_streaming.h>
 #include <xcore/interrupt.h>
 
+#include <platform.h>
+
 #include "mic_array_vanilla.h"
 #include "mic_array/cpp/Prefab.hpp"
 #include "mic_array.h"

lib_mic_array/lib_build_info.cmake

@@ -0,0 +1,15 @@
+set(LIB_NAME lib_mic_array)
+set(LIB_VERSION 5.2.0)
+set(LIB_DEPENDENT_MODULES "lib_xcore_math(2.2.0)")
+set(LIB_INCLUDES 
+    api
+    api/mic_array
+    api/mic_array/cpp
+    api/mic_array/etc
+    api/mic_array/impl
+    src 
+    src/etc
+)
+set(LIB_COMPILER_FLAGS -g -Os)
+
+XMOS_REGISTER_MODULE()

settings.yml

@@ -0,0 +1,14 @@
+---
+project: lib_mic_array
+title: Mic Array Library
+version: 5.1.0
+
+documentation:
+  exclude_patterns_path: doc/exclude_patterns.inc
+  doxygen_projects:
+    lib_mic_array:
+      doxyfile_path: doc/Doxyfile.inc
+  pdfs:
+    doc/programming_guide/index:
+      pdf_title: "{{title}} - Programming Guide"
+      pdf_filename: "{{project}}_programming_guide_v{{version}}"