xplat.cfg contents - John Arrizza

Overview

The xplat.cfg contains cross-platform information used by various scripts to properly perform their functions correctly on different OSes.

See below for an example xplat.cfg.

scripts

The scripts that use xplat.cfg are in the xplat-utils repo. This contains all of the scripts needed for building, running, testing all of the repos. See xplat-utils

The parsing code is in tools/xplat_utils/cfg.py
The various scripts are in tools/xplat_utils/do_xx.py
see tools/xplat_utils/zpm_app.py, _load_valid_cmds() for the mapping from zpm commands to scripts that use these config values.

xplat section

Holds various names, data and info across all repo types and techs (see "mod_type" and "mod_tech" below).

Note many of these are used in python modules and ruby gems.

See tools/pyproject_template.toml
See tools/gem_template.gemspec

xplat.version

The version string used for the app/module/gem/library.

Type: str

Used by:

zpm check
zpm post-ver
zpm publish
tools/xplat_utils/gen_files.py

xplat.mod_name

The name of the application/module project.

It must contain only dashes "-". No initial or trailing dashes.
Note: the "dart" tech requires the use of underscores instead of dashes.
no spaces
lower case recommended. Upper case has not been tested

Note another item "mod_dir_name" is automatically created based on this value. It has the same value as mod_name, but dashes are converted to underscores.

Type: str

Used by:

zpm check
zpm doc
zpm publish

xplat.mod_dir_name

Automatically created from "mod_name".

This holds the name of the python module in the src directory:

py-dual-sorter          <== top level directory
  - src
      - py_dual_sorter  <== pypi module name used in the import

Type: str

Used by:

zpm check
zpm clean
zpm publish
tools/xplat_utils/utils_common.py

xplat.desc

A short description of the app/module. This is used in documentation, license, etc.

Type: str

Used by:

tools/xplat_utils/gen_files.py

xplat.slug

The web page name used on arrizza.com.

'N/A' is used for private or WIP repos
typically, it is the same as mod-name but can have embedded variables:
- {mod_name}: uses the value 'mod_name' above e.g. python-{mod_name} becomes python-on-the-fly-stats
- {mod_dir_name}: uses "mod_dir_name" above
- {mod_type}: uses value of "mod_type" above

Type: str

Used by:

zpm post-ver
zpm publish

xplat.is_module

Boolean value indicating it is a module or an app.

if it is False, it is an app
if it is True, it is a python module, C/C++ library, Ruby gem, etc.

Type: str

Used by:

zpm check
zpm clean
zpm lint
zpm publish
zpm ut
zpm ver
zpm_env
tools/xplat_utils/gen_files.py
tools/xplat_utils/utils_common.py
tools/xplat_utils/zpm_utils.py

xplat.mod_type

Indicates if this module is publicly available.

"public" indicates it can show up on arrizza.com. Some projects are marked public but I have not published them (yet).
"private" indicates that it will not be visible, it is either for personal use only or is WIP.

Type: str, enumerated values only

Used by:

zpm publish

xplat.mod_tech

Indicates the underlying primary technology used by this project. Note that some projects are cross-technology e.g. pyalamake uses python but generates a Makefile which uses C/C++ and Arduino code. Also see do_install.sub_techs below.

Currently, these are the recognized techs:

"python" - for python apps and modules
"cpp" - for C/C++ apps and libraries
"arduino" - for Arduino apps (note: libraries are under construction)
"ruby" - for Ruby apps and gems
"dart" - for Dart/Flutter apps and gems
"other" - for perl, 3D printing, FPGA, and others

Type: str, enumerated values only

Used by: most zpm commands

xplat.lic_year

The "as of" year for the license and copyright. This is an indication of when the project was first publicly posted. See LICENSE.txt for the full license and info.

Type: str, but is a valid 4 digit year

Used by:

zpm publish
zpm_doc
gen_files

xplat.license

The license type. Currently only uses "MIT".
Used in python modules and ruby gems as required for publishing them.
see pyproject_template.toml for python modules or gem_template.gemspec for ruby gems

Type: str

Used by:

zpm check

xplat.source_url

Used in python modules and ruby gems to provide a path to the git server's source code page
see pyproject_template.toml for python modules or gem_template.gemspec for ruby gems

Type: str, but is a valid hyperlink

Used by:

zpm publish

xplat.download_url

Used in python modules to indicate how to download the module.
see pyproject_template.toml for python modules

Type: str, but is a valid hyperlink

Used by:

zpm publish

xplat.author

Used in python modules and ruby gems as required for publishing them.
see pyproject_template.toml for python modules or gem_template.gemspec for ruby gems

Type: str

Used by:

zpm publish

xplat.email

Used in python modules and ruby gems as required for publishing them.
see pyproject_template.toml for python modules or gem_template.gemspec for ruby gems

Type: str, but is a valid email address

Used by:

zpm publish

xplat.long_desc_type

Used in python modules and ruby gems as required for publishing them. Indicates the README type. Currently only text/markdown is used.

Type: str, but is a valid type

Used by:

zpm publish

do_install

Holds information required by the do_install script to do installations of tools, etc.

do_install.sub_techs

Holds a list of other techs used in this project.
valid techs: python arduino cpp ruby dart 3d-print fpga
do not use: other

Type: list, valid xplat.mod_tech values

Used by:

zpm install
zpm lint

do_publish

Various info used by the do_publish script to publish a Python module or Ruby gem.

do_publish.disallow

Some repos are only templates but are marked as a module/gem. If the current mod_name matches any of these values, it will not be published to pypi or rubygem.org.

Type: list of a repo-names

Used by:

zpm publish

do_clean

Various info used by the do_clean script.

do_clean.sub_techs

An optional list of additional techs to clean up. The actual files/dirs is dependent on the tech.

Type: list, valid xplat.mod_tech values

Used by:

zpm clean

do_clean.files

An optional list of file regex patterns to delete

Type: list, valid file paths or regex patterns

Used by:

zpm clean

do_clean.dirs

An optional list of directory regex patterns to delete

Type: list, valid directory paths or regex patterns

Used by:

zpm clean

do_lint

Various info used by the do_lint script.

do_lint.implemented

if lint is implemented for this tech/repo, set to True.
False otherwise

Type: bool

Used by:

zpm lint

do_lint.include_tools

Boolean flag to indicate if the ./tools directory should be included in the lint.

Type: bool

Used by:

zpm lint

do_lint.excludes

List of files/directories to execlude from lint checking

Type: list, valid file/directory paths

Used by:

zpm lint

do_lint.src_dirs

Any additional directories to check. Currently used only in cpp/arduino mod_techs.

Type: list, valid directory paths

Used by:

zpm lint

do_doc

Various info used by the do_doc script.

do_doc.implemented

if documentation is implemented for this tech/repo, set to True.
False otherwise

Type: bool

Used by:

zpm doc

do_doc.doxy_exclude

Various files or directories to exclude from being parsed by doxygen or other doc generators.

Type: list, valid file/directory paths

Used by:

zpm doc

do_doc.doxy_include

Various directories to include for parsing by doxygen or other doc generators.

Type: list, valid file/directory paths

Used by:

zpm doc

do_post_ver

Various info used by the do_post_ver. This is used to post verification information, see Verification Test Results

do_post_ver.dst_dir

The directory to save the genned verification html files. These are all accumulated and published on arrizza.com/web-ver

Type: str, valid directory path

Used by:

zpm post-ver

do_post_ver.src_dir

The directory where the verification data is stored. Typically, it is out/ver.

Type: str, valid directory path

Used by:

zpm post-ver

do_post_ver.pypi_url

The pypi url that contains the python module. If it is an app or PYPI is not applicable, use "N/A".

Type: str, valid hyperlink

Used by:

zpm post-ver

do_post_ver.repo_url

The url for the associated repo. Currently, these are on bitbucket.org for the repos in arrizza.com.

For example:

repo_url = 'https://bitbucket.org/arrizza-{mod_type}/{mod_name}'

{mod_type} is replaced by xplat.mod_type value
{mod_name} is replaced by xplat.mod_name value

If it is a private repo, use 'N/A'.

Type: str, valid hyperlink or 'N/A'

Used by:

zpm post-ver

do_mk_gen

Additional configuration for makefile generation.

do_mk_gen.implemented

if makefile generation is implemented for this tech/repo, set to True.
False otherwise

Type: bool

do_mk_gen.mainline

The mainline python script to run that generates the makefiles
if blank then not run

Type: str, valid path to python script

Used by:

tools/xplat_utils/zpm_utils.py

do_mk_gen.reset_coverage

If True, reset coverage.

Type: bool

Used by:

tools/xplat_utils/zpm_utils.py

do_mk_gen.do_coverage

if True, run with coverage

Type: bool

Used by:

tools/xplat_utils/zpm_utils.py

do_mk_gen.report_coverage

If True, report coverage

Type: bool

Used by:

tools/xplat_utils/zpm_utils.py

do_mk_build

Additional configuration for makefile build.

do_mk_build.implemented

if makefile build is implemented for this tech/repo, set to True.
False otherwise

Type: bool

Used by:

tools/xplat_utils/zpm_utils.py

do_mk_build.mk_targets

A list of makefile targets to run
if blank then not run

Type: list, valid makefile targets for the current OS

Used by:

zpm mk-build
tools/xplat_utils/zpm_utils.py

doit

Additional configuration for doit.

doit.implemented

if doit is implemented for this tech/repo, set to True.
False otherwise

Type: bool

Used by:

zpm doit
tools/xplat_utils/zpm_utils.py

doit.mainline

The mainline script, or makefile target to run

Type: str, valid path to mainline script

Used by:

zpm doit
tools/xplat_utils/zpm_utils.py

doit.mainrunner

The tech of the the mainline runner, one of:

bash - a bash script
python - a python script
ruby - a ruby script
dart - a dart app
make - a makefile target

Type: str, one of the enumerated values

Used by:

zpm doit
tools/xplat_utils/zpm_utils.py

doit.upload

if True upload the executable to the microcontroller
assumes make target is "{mod_name}-upload"

Type: bool

Used by:

zpm doit
tools/xplat_utils/zpm_utils.py

do_ver

Additional configuration for verification testing

do_ver.implemented

if verification testing is implemented for this tech/repo, set to True.
False otherwise

Type: bool

Used by:

zpm ver
tools/xplat_utils/zpm_utils.py

do_ver.reset_coverage

Reset coverage for this mod_tech.
if ver and ut are both implemented, then ver must reset_coverage and ut must not.

Type: bool

Used by:

zpm ver
tools/xplat_utils/zpm_utils.py

do_ver.cov_dirs

Indicates which directories to include in coverage statistics.

Type: list, valid directory paths

Used by:

zpm ver

do_ver.excludes

Any files/directories to exclude from the coverage report

Type: list, valid file/directory paths

Used by:

zpm ver

do_ver.gen_report

The python script to generate the verification report.
Typically ver/helpers/gen_report.py

Type: str, valid path to python script

Used by:

zpm ver

do_ut

Various info used by the do_ut script.

do_ut.implemented

if unit testing is implemented for this tech/repo, set to True.
False otherwise

Type: bool

Used by:

zpm ut
tools/xplat_utils/zpm_utils.py

do_ut.mk_target

Use a makefile target for running UTs (debug/ut) and coverage
set to blank for techs other than cpp and arduino

Type: str, valid makefile target to run

Used by:

zpm ut

do_ut.reset_coverage

Reset coverage report
if ver and ut are both implemented, then ver must reset_coverage and ut must not.

Type: bool

Used by:

do_ut.cov_dirs

Indicates which directories to include in coverage statistics.

Type: list, valid directory paths

Used by:

zpm ut

do_ut.excludes

Various directories or files to exclude from the coverage report

Type: list, valid file/directory paths

Used by:

zpm ut
tools/xplat_utils/do_coverage.py

cpip

Indicates any CPIP common packages to retrieve or publish to.

(CPIP is my very simple "package manager", see CPIP User Guide)

cpip.root_dir

The location of the packages. This is a mounted shared drive between my windows, ubuntu and macos laptops.

Type: str, valid directory path

Used by:

zpm cpip-pull
zpm cpip-publish
zpm lint

cpip.root_dir.win

An override for windows (because of the drive letter)

Type: str, valid directory path

Used by:

zpm cpip-pull
zpm cpip-publish
zpm lint

cpip.packages

A list of packages used by this project

Type: list, valid CPIP packages

Used by:

zpm cpip-pull
zpm cpip-publish

gen_files

gen_files.gen_type

Generate various files required for various techs.

gen_constants is the default. It generates a file that has the xplat.version as a constant appropriate for the tech.

Type: str, valid enumerate value

Used by:

tools/xplat_utils/gen_files.py

gen_files.subdir

Default is to generate the constants file in root of the app/module
Use subdir to name a sub-directory

Type: str, valid sub-directory path

Used by:

tools/xplat_utils/gen_files.py

Sample xplat.cfg

A typical xplat.cfg looks like this:

[xplat]
; the version string
version = '0.0.1'
; the module name (with dashes)
mod_name = 'your-project'
; document description
desc = 'a description of your project'
; web slug; use 'N/A' for projects not on the web
slug = 'N/A'
; flag indicating this is a module/library (True) or an app (False)
is_module = False
; indicating if private or public
mod_type = 'private'
; which tech is used for this project: python, cpp, arduino, ruby, dart, other
mod_tech = 'python'
; license data
lic_year = 2024
;
; == typically do not change from here on
;
; the license for the module
license = 'MIT'
; the url for the source code link
source_url = 'https://bitbucket.org/arrizza-{mod_type}/{mod_name}/src/master'
; the url for the download link
download_url = 'https://bitbucket.org/arrizza-{mod_type}/{mod_name}/get/master.zip'

; the author name
author = 'Your Name'
; the contact email
email = 'youremail@gmail.com'
; the type of the description file used
long_desc_type = 'text/markdown'

; --------------------
; additional cfg for install
[do_install]
; additional techs to install for
sub_techs =

; --------------------
; additional cfg for do_publish
[do_publish]
; disallow these modules from being published; comma separated list
disallow = module-name, devpy-mod-template, devrb-gem-template

; --------------------
; additional cfg for do_clean
[do_clean]
; additional techs to clean for
sub_techs =
; file patterns to delete
files =
; directory patterns to delete
dirs =

; --------------------
; additional cfg for do_lint
[do_lint]
; set to true if implemented
implemented = True
; include the tools directory
include_tools = False
; exclude files/directories
excludes =
; for cpp/arduino: src directories
src_dirs =

; --------------------
; additional cfg for do_doc
[do_doc]
; set to true if implemented
implemented = True
; additional exclude directories (if any)
doxy_exclude = build
               debug
               release
               cmake-build-debug
               cmake-build-release
               sys-tests
; additional include directories (if any)
doxy_include =

; --------------------
; additional cfg for do_post_ver
[do_post_ver]
; directory to save verification html files
dst_dir = '~/projects/web-ver'
; directory to get verification html files
src_dir = 'out/ver'
; PyPi URL for python modules; use 'N/A' not a module
; e.g. python: https://pypi.org/project/{mod_name}
; e.g. ruby  : https://rubygems.org/gems/{mod_dir_name}
pypi_url = 'N/A'
; repo URL; note can only be public
repo_url = 'N/A'

; --------------------
; additional cfg for do_mk_gen
[do_mk_gen]
; set to true if implemented
implemented = False
; mainline script to run; if blank then not run
mainline =
; reset coverage
reset_coverage = False
; run with coverage
do_coverage = False
; report coverage
report_coverage = False

; --------------------
; additional cfg for do_mk_build
[do_mk_build]
; set to true if implemented
implemented = False
; makefile targets; if blank then not run
mk_targets =

; --------------------
; additional cfg for doit
[doit]
; set to true if implemented
implemented = True
; mainline script to run
mainline = lib/main.py
; mainline runner, one of: bash, python, make
mainrunner = 'python'
; if True upload the executable to the microcontroller; assumes make target is "xx-upload"
upload = False

; --------------------
; additional cfg for do_ver
[do_ver]
; set to true if implemented
implemented = False
; reset coverage
reset_coverage = True
; the coverage dirs to report
cov_dirs =
; exclude directories/files
excludes =
; gen report
gen_report = 'ver/helpers/gen_report.py'

; --------------------
; additional cfg for do_ut
[do_ut]
; set to true if implemented
implemented = False
; use makefile for running UTs (debug/ut) and coverage; set to blank for other techs
mk_target =
; reset coverage
reset_coverage = False
; the coverage dirs to report
cov_dirs =
; exclude directories/files
excludes =

; --------------------
; list of packages from a common library
[cpip]
root_dir = ~/projects/cpip
root_dir.win = y:/cpip
; used for local server testing of CPIP
;server_root = 'https://10.0.0.10/web-cpip'
; list of packages
packages =

[gen_files]
gen_type = 'gen_constants'
subdir = ''