darcsver-1.7.2.egg/share/doc/python-darcsver/README.txt

   1 darcsver - generate version numbers from darcs revision control history
   2 =======================================================================
   3
   4 What Does It Do
   5 ---------------
   6
   7 Create files containing version numbers, based upon the latest darcs
   8 release tag.
   9
  10 If your source tree is coming from darcs (i.e. it is in a darcs
  11 repository), this tool will determine the most recent release tag,
  12 count the patches that have been applied since then, and compute a
  13 version number to be written into _version.py (and optionally other
  14 version files). This version number will be available by doing:
  15
  16  from your_package_name import __version__
  17
  18 Source trees that do not come from darcs (e.g. release tarballs, nightly
  19 tarballs) and are not within a darcs repository should instead, come with a
  20 _version.py that was generated before the tarball was produced. In this case,
  21 this tool will quietly exit without modifying the existing _version.py .
  22
  23 'release tags' are tags in the source repository that match the following
  24 regexp:
  25
  26  ^your_package_name-(\d+)(\.(\d+)(\.(\d+))?)?((a|b|c|rc)(\d+))?
  27
  28
  29 Installation
  30 ------------
  31
  32 With easy_install:
  33
  34   easy_install darcsver
  35
  36 Alternative manual installation:
  37
  38   tar -zxvf darcsver-X.Y.Z.tar.gz
  39   cd darcsver-X.Y.Z
  40   python setup.py install
  41
  42 Where X.Y.Z is a version number.
  43
  44 Alternative to make a specific package use darcsver without installing
  45 darcsver into the system:
  46
  47   Put "setup_requires=['darcsver']" in the call to setup() in the
  48   package's setup.py file.
  49
  50
  51 Usage
  52 -----
  53
  54 There are two ways to use this: the command-line tool and the
  55 setuptools plugin.
  56
  57 To use the command-line tool, execute it as:
  58
  59 darcsver $PACKAGE_NAME $PATH_TO_VERSION_PY
  60
  61
  62 To use the setuptools plugin (which enables you to write "./setup.py
  63 darcsver" and which cleverly figures out where the _version.py file
  64 ought to go), you must first package your python module with
  65 `setup.py` and use setuptools.
  66
  67 The former is well documented in the distutils manual:
  68
  69   http://docs.python.org/dist/dist.html
  70
  71 To use setuptools instead of distutils, just edit `setup.py` and
  72 change
  73
  74   from distutils.core import setup
  75
  76 to
  77
  78   from setuptools import setup
  79
  80
  81 References
  82 ----------
  83
  84 How to distribute Python modules with Distutils:
  85
  86   http://docs.python.org/dist/dist.html
  87
  88
  89 Setuptools complete manual:
  90
  91   http://peak.telecommunity.com/DevCenter/setuptools
  92
  93
  94 Thanks to Yannick Gingras for providing the prototype for this
  95 README.txt.