Quick Start - John Arrizza

Overview

Top level description of available zpm commands

See:

User Guide for User Guide for more detailed zpm documentation.

Notes:

"xplat" means "cross-platform"
Individual projects may have additional commands needed
See doc/test_process.md in the individual projects for information specific to that project.

zpm commands

xplat-install

Install zpm and other cross-platform tools. No parameters accepted

env-install

install python virtualenv or ruby gems. options: fast (default), sync

ard-install

install arduino libraries from tools/arduino_reqmts.txt

clean

clean up all local files, python virtual environment, output files, etc. for the project. In general, the repo should be equivalent to a fresh clone (roughly speaking).
option: lite (default)
- TODO:
option: full
- TODO:
Note: does NOT uninstall OS packages.

install

Installs Python pip modules or ruby gems as needed for these scripts and project.
other languages use other installers as needed
use "full" to install any OS packages needed for the project
This is normally only done once, but can be used to refresh/update the OS packages if necessary.

doc

For most projects runs doxygen. See out/doc/html/index.html for HTML version.
Use option "true" to generate a PDF, see out/ directory for it.
Some languages have their own documentation generator, for example ruby uses TODO.

check

Checks various aspects of the current setup e.g. package versions, existence of config files, contents of config files, etc.

lint

Run static analysis:

for python: pylint (default) or ruff
for ruby: rubocop
for C/C++ and Arduino: cppcheck (default) or clang-tidy
for 3D openscad projects: runs openscad which can report warnings and errors
for others (golang, flutter, perl): these are specific to those projects

mk-gen

generates cross-platform C/C++ and arduino makefiles using pyalamake
typically named gen.py
the makefile is specific to the current OS e.g. Makefile.ubuntu, Makefile.macos, Makefile.msys2

mk-build

builds C/C++ projects using the makefile for the current OS

mk-run

run the makefile with a target and any optional args provided
the makefile is specific to the current OS e.g. Makefile.ubuntu, Makefile.macos, Makefile.msys2

mk-upload

upload a makefile target. Uses xx-upload, where xx is the target given on CLI or the value in doit.mainline

cpip-pull

update local CPIP libraries

cpip-publish

push local code/libraries to remote CPIP

cpip-get

get CPIP library

doit

Run the app or sample code to run the module/library.
run the app or sample use of the module
All parameters are accepted.

ver

Run verification (if implemented) scripts.
most repos use medver-pytest
see medver tutorial for an example of how to set this up and run them

ut

Run unit tests (if implemented).

python: pytest
ruby: TODO ??
C/C++: GTest
arduino: GTest
other: depends on the specific project

ver-info

generate verification information. No parameters needed.

post-ver

post verification information, if any

publish

Publish a Python module to PyPi or ruby gem to rubygems.org
Does not exist or not implemented for applications or for C/C++ projects.
Note, I currently do have a way to publish to my website. These are listed here: CPIP. see cpip-publish below

coverage-reset

reset report coverage

coverage-run

report coverage

run

do general setup and then run the given script. Default is "doit"

setup-outdir

setup: create output directory
typically used in internal bash scripts

setup-clean-outsubdir

setup: clean outdir sub-directory
typically used in internal bash scripts

setup-gen-files

setup: gen files e.g. LICENSE.txt etc.
typically used in internal bash scripts

setup-gen-setup-cfg

setup: gen setup.cfg
typically used in internal bash scripts

Typical use

The zpm commands are typically run in the following order for setting up and running a repo on this site. Other languages and repo techs may require other commands

# do basic setup
tools/zpm xplat-install
zpm env-install

# for arduino repos
zpm ard-install

# clean temporary data e.g. the out directory
zpm clean

# install any additional files, modules, libraries, etc. needed by the project
zpm install full

# generate doxygen html
zpm doc       # HTML only
zpm doc true  # HTML and PDF generated

# check configs and files are okay
zpm check

# run a linter:
#   python: pylint or optionally ruff
#   ruby  : rubocop
#   c/c++ : cppcheck or optionally clang-tidy
zpm lint
zpm lint ruff
zpm lint clang-tidy  

# publish modules/gems as needed
#   python: publish to pypi.org
#   ruby  : publish to rubygems.org
zpm publish

# use to update venv from local python repositories
./do_update

# run it
./do_ver # run verification (if implemented)
./do_ut  # run unit tests (if implemented)

./doit   # run the app or sample code to run the module/library