# -*- mode: org; mode:auto-revert; -*-
* OSDEV Versioning Tool

This tool will create the OSDEV version information to embed into the
mLogic products, based on the "OSDEV Component Lifecycle Management v1.x"
specifications

The core of this approach is based on the DMX versioning tool for
C/C++. The script osdev_create_version_include.sh uses environmental
variables such as OSDEV_SRC_DIR to point to the git repository tree
and configuration files for the component to be versioned. 

There has to be three valid configuration files supplied to the tool to
create a valid component version.

- mlogic_config.txt
  Managed in this repository. This defines the Architecture and Mlogic
  release information

- product_config.txt
  Managed in the component repository. This defines the
  product/component specific information

- customer_config.txt
  Manage in the build environment. This (if available) defines the
  customer specific information for the component.

See the example configuration files in the osdev_config directory for
more information on the contents.

* General Usage
  This repository should be added as a submodule, or similar to the main
  repository.

  Where possible the script defaults to using the configuration files
  found in the ${OSDEV_SRC_DIR}/osdev_config folder. 

| Variable              | Default if undefined in environment    | Description                                    |
|-----------------------+----------------------------------------+------------------------------------------------|
| OSDEV_SRC_DIR          | Arg 1 (No Default)                     | path to component git repository root          |
| OSDEV_VERSION_HDR_DIR  | Arg 2 (No Default)                     | output directory for osdev_version file         |
| OSDEV_CONFIG_DIR       | ${OSDEV_SRC_DIR}/osdev_config            | path to component configuration file directory |
| OSDEV_VERSION_PRODUCT  | ${OSDEV_CONFIG_DIR}/product_config.txt  | product configuration filename                 |
| OSDEV_VERSION_CUSTOMER | ${OSDEV_CONFIG_DIR}/customer_config.txt | path to customer configuration file            |

- For debugging purposes only:
| OSDEV_GIT_DIR        | Directory where script exists (pwd)           | path to this git repository   |
| OSDEV_VERSION_MLOGIC | ${OSDEV_GIT_DIR}/osdev_config/mlogic_config.txt | Architecture version filename |

Note for Yocto/McGraw Environment:
$OSDEV_VERSION_CUSTOMER should be set to ${MEYN_CUSTOMER_CONFIG_ROOT}/customer_config.txt 

The script creates an include file that contains constants that should
be used to identify a component. The generated source is the best
reference for the various defined elements. 

There are two elements that are required. They are:

- _VER_OSDEV_IDENTIFIER_
  The full OSDEV component identifier. Visible to the external world, via
  IU or service version.
- _VER_BUILD_EMBED_SHA_ 
  The full embedded build fingerprint. Visible to developers/R&D with
  the command "grep -e ":git:.*:tig:" <fingerprinted binary>

* Defining the Product Identifier
  This tool uses the folder osdev_version in the root of the git
  repository to contain the default product and customer
  identifiers. 

  To start using this tool you must: 
  - copy the osdev_version folder from this repository to the root of the
    product git repository.

  - remove the example mlogic_config.txt from the copied folder
  - if required - remove the example customer_config.txt from the copied folder

  - edit the product identification file.

  Once this is done, you can use the appropriate mechanism to use this
  tool to identify your product.

* C/C++ 
 

include the "osdev_verison.h" in the source, and define <
- How a build fingerprint is embedded into a binary.
#+BEGIN_SRC c++
#include "osdev_version.h"
/* OSDEV Component identifier  define build fingerprint */
_static const char *build_id=_VER_BUILD_EMBED_SHA_
#+END_SRC

*** PyUAF

*** QT
      An example of using the Component Identifier used in QT User
      interfaces.
#+BEGIN_SRC c++ Qt Gui
#include "osdev_version.h"

/* OSDEV Component identifier */
a.setProperty("VersionString", QString("%1")
                 .arg(_VER_OSDEV_IDENTIFIER_)
        );
    #+END_SRC

*** Cmake as git submodule
    One mechanism to relate repositories is to use the "git submodule
    add" command, and add the appropriate version of the
    osdev_create_version_include as a submodule in the project folder.

    These dependencies are tightly coupled, and have to be adjusted when
    moving from development to release.

    Add it to the projects CMakeLists.txt as below, and The project should build
    as usual.

#+BEGIN_SRC cmake

# point the tool to this repository to create version from.
set (ENV{OSDEV_SRC_DIR} ${CMAKE_SOURCE_DIR})

# To override default source for product or source information.
# see the Cmakelists in the osdev_create_version_include folder.

# Add Version control to the Cmake source tree
ADD_SUBDIRECTORY(osdev_create_version_include)

# add version directory to included directories
INCLUDE_DIRECTORIES(${OSDEV_VERSION_HEADER_DIR})

#+END_SRC
*** Cmake as external source
    This is another approach to managing the architecture dependency,
    using the external source mechanism to add the tool to the source
    tree as a parameter of the Cmake file, or as an environmental
    variable defined by the build system. 

    copy the ExternalHsoaVersion into a local cmake include folder. if
    one does not exist then create it, and add this to your CMakelists.txt

#+BEGIN_SRC cmake
# include cmake modules
LIST( APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake )
MESSAGE("CMAKE MODULE PATH:${CMAKE_MODULE_PATH}")
#+END_SRC

    Then you need to include the External resource in your project. You
    can do this with the following:

#+BEGIN_SRC cmake

# define extra git repository Version parameters
SET(OSDEV_VERSION_TAG "R1_XD1.0.0E0.0.0")
SET(OSDEV_VERSION_REPO "git@gitlab.osdev.nl:OpenSystemsDevelopment/osdev_versioning.git")

# include OSDEV Version tool as external asset
INCLUDE( ExternalHsoaVersion )

# add version directory to included directories
INCLUDE_DIRECTORIES(${OSDEV_VERSION_HEADER_DIR})

#+END_SRC

*Note* Defining the variable in the CMake file, overrides any
environmental settings in the external version approach.


* Python
   

* JavaScript 


* Ansible