About ===== TurnKey Linux Python toolkit template, with two example commands: 1) example # dummy example command that parses options 2) prog # prints 'prog' not implemented Features ======== * leverage common infrastructure (pyproject-common): - pyproject.py Python module for wrapper cli - shared base Makefiles - shred utility scripts * integrated help support (e.g., command docstrings are automatically interpreted by wrapper) * debian packaging support * flexible toolkit execution syntax:: # lists available commands project # runs pylib/cmd_command.py:main() project command arg1 arg2 ... project-command arg1 arg2 ... # if only one command available, this will run it project arg1 arg2 * wrapper environment setup - automatically sets up pylib into your python path - automatically sets up libexec into your PATH * versioning support Looks for version in the following places (by order): 1) <INSTALL_PATH>/version.txt (if it exists) 2) debian/changelog (if it exists - parsed with dpkg-parsechangelog) 3) `autoversion HEAD` To print out program version: project --version * integrated profiler support project -p subcommand args... project-subcommand --profile args... * integrated debugging support project -d subcommand args... project-subcommand --debug args.. Usage ===== * initialization:: cp -a pyproject newproject cd newproject && make init * update packaging files eg. debian/control with descriptions and dependencies * remove example dummy commands? pylib/cmd_printargs.py pylib/cmd_prog.py * add programs to the toolkit as pylib/cmd_<subcmd>.py * Makefile help usage make || make help * update links (when you have added or removed commands) make updatelinks Remember, you can run toolkit commands like this:: pylib/cmd_<subcmd>.py arg1 arg2 ... <progname>-<subcmd> arg1 arg2 ... <progname> <subcmd> arg1 arg2 ... * documentation / integrated help Usage: <progname> # prints high level overview of programs + help <progname>-<command> -h # extended help Notes: - The first line of a cmd_* module docstring is the short usage desc. - commands that have a usage() function, support the -h flag for extended help. - The help module defines a usage decorator for convenience. Example usage (see cmd_printargs for an example):: import help @help.usage(__doc__) def usage(): print "Syntax: foo" Advanced: Normally, the order of the commands printed by <progname> is determined by their sort order. If you want to manually tweak with the order, then list the desired order in wrapper.CliWrapper.COMMANDS_USAGE_ORDER. Empty string values COMMANDS_USAGE_ORDER symbolize empty lines/seperators. * install:: make install prefix=... # prefix defaults to /usr/local * uninstall:: make uninstall # prefix defaults to /usr/local * tag the latest commit as a versioned release: # this will ask you for a tag message (which may include release notes) # and create a tag signed by your GPG key git tag -s v1.0.1 (if available, use of git-tag-release is recommended) Makefile extension mechanism ============================ pyproject-common's Makefiles (pyproject.mk and debian-rules.mk) are designed to be configurable and extendable with *define* based hooks which are set BEFORE including the shared Makefile because target prerequisites are evaluated at include time:: <target>/pre # rules before default body (default: empty) <target>/post # rules after default body (default: empty) <target>/deps # override default dependencies for a rule <target>/deps/extra # extra dependencies for rule (default: empty) Special case - if you want to override built in built-in rules for a target, you'll need to define them AFTER including the shared Makefile:: <target>/body # body of rules (default: defined, but can be overridden) To override built-in variables you'll need to define them AFTER the include. Most pyprojects don't need to extend the default Makefiles, but extending and overriding default behavior is occasionally needed to satisfy special use cases (e.g., connagent and opus). For example:: $ cd opus $ cat Makefile PATH_INSTALL_TEMPLATES = $(PATH_INSTALL)/templates define help/post @echo @echo "templates # make templates/generated" endef templates: cd templates && ./generate.py build/deps/extra = templates define install/post install -d $(PATH_INSTALL_TEMPLATES) cp -a templates/generated $(PATH_INSTALL_TEMPLATES) endef .PHONY: templates PYPROJECT_SHARE_PATH ?= /usr/share/pyproject include $(PYPROJECT_SHARE_PATH)/pyproject.mk Makefile API ============ pyproject.mk:: INSTALL_SUID # if not empty string, install program suid INSTALL_NODOC # if not empty string, compile without docstrings EXTENDABLE_TARGETS = help build install uninstall clean debian-rules.mk:: EXTENDABLE_TARGETS = build clean binary-indep binary-arch