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