← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/version_info.txt

  • Committer: John Arbash Meinel
  • Date: 2011-05-11 11:35:28 UTC
  • mto: This revision was merged to the branch mainline in revision 5851.
  • Revision ID: john@arbash-meinel.com-20110511113528-qepibuwxicjrbb2h
Break compatibility with python <2.6.

This includes auditing the code for places where we were doing
explicit 'sys.version' checks and removing them as appropriate.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/version_info.txt
1
 
==========================
2
 
Using ``bzr version-info``
3
 
==========================
4
 
 
5
 
Overview
6
 
========
7
 
 
8
 
This document describes ways of using ``bzr version-info`` as part of a
9
 
build routine to embed version information into a final project.
10
 
 
11
 
 
12
 
Python Project
13
 
==============
14
 
 
15
 
TODO: Figure out how to attach into ``setup.py``
 
1
Exporting version information
 
2
=============================
 
3
 
 
4
Getting the last revision number
 
5
--------------------------------
 
6
 
 
7
If you only need the last revision number in your build scripts, you can
 
8
use the ``revno`` command to get that value like this::
 
9
 
 
10
  $ bzr revno
 
11
  3104
 
12
 
 
13
 
 
14
Getting more version information
 
15
--------------------------------
 
16
 
 
17
The ``version-info`` command can be used to output more information
 
18
about the latest version like this::
 
19
 
 
20
  $ bzr version-info
 
21
  revision-id: pqm@pqm.ubuntu.com-20071211175118-s94sizduj201hrs5
 
22
  date: 2007-12-11 17:51:18 +0000
 
23
  build-date: 2007-12-13 13:14:51 +1000
 
24
  revno: 3104
 
25
  branch-nick: bzr.dev
 
26
 
 
27
You can easily filter that output using operating system tools or
 
28
scripts. For example::
 
29
 
 
30
  $ bzr version-info | grep ^date
 
31
  date: 2007-12-11 17:51:18 +0000
 
32
 
 
33
The ``--all`` option will actually dump version information about
 
34
every revision if you need that information for more advanced
 
35
post-processing.
 
36
 
 
37
 
 
38
Python projects
 
39
---------------
 
40
 
 
41
.. TODO: Figure out how to attach into ``setup.py``
16
42
 
17
43
 
18
44
If using a Makefile to build your project, you can generate the version
19
45
information file as simply as::
20
46
 
21
47
  library/_version.py:
22
 
        bzr version-info --format=python > library/_version.py
 
48
        bzr version-info --format python > library/_version.py
23
49
 
24
50
This generates a file which contains 3 dictionaries:
25
51
 
26
 
  `version_info`: A dictionary containing the basic information about the
27
 
                  current state.
28
 
 
29
 
  revisions: A dictionary listing all of the revisions in the history of
30
 
             the tree, along with the commit times and commit message.
31
 
             This defaults to being empty unless ``--all`` or
32
 
             ``--include-history`` is supplied. This is useful if you
33
 
             want to track what bugfixes, etc, might be included in the
34
 
             released version. But for many projects it is more
35
 
             information than they need.
36
 
 
37
 
  `file_revisions`: A dictionary listing the last-modified revision for
38
 
                    all files in the project. This can be used similarly
39
 
                    to how ``$Id$`` keywords are used in CVS controlled
40
 
                    files. The last modified date can be determined by
41
 
                    looking in the ``revisions`` map. This is also empty by
42
 
                    default, and enabled only by ``--all`` or
43
 
                    ``--include-file-revisions``.
44
 
 
45
 
Check Clean
46
 
===========
 
52
  * `version_info`: A dictionary containing the basic information about the
 
53
    current state.
 
54
 
 
55
  * `revisions`: A dictionary listing all of the revisions in the
 
56
    history of the tree, along with the commit times and commit
 
57
    message.  This defaults to being empty unless ``--all`` or
 
58
    ``--include-history`` is supplied. This is useful if you want to
 
59
    track what bug fixes, etc, might be included in the released
 
60
    version. But for many projects it is more information than needed.
 
61
 
 
62
  * `file_revisions`: A dictionary listing the last-modified revision
 
63
    for all files in the project. This can be used similarly to how
 
64
    ``$Id$`` keywords are used in CVS-controlled files. The last
 
65
    modified date can be determined by looking in the ``revisions``
 
66
    map. This is also empty by default, and enabled only by ``--all``
 
67
    or ``--include-file-revisions``.
 
68
 
 
69
 
 
70
Getting version info in other formats
 
71
-------------------------------------
 
72
 
 
73
Bazaar supports a template-based method for getting version information in
 
74
arbitrary formats.  The ``--custom`` option to ``version-info`` can be
 
75
used by providing a ``--template`` argument that contains variables that
 
76
will be expanded based on the status of the working tree.  For example, to
 
77
generate a C header file with a formatted string containing the current
 
78
revision number::
 
79
 
 
80
 bzr version-info --custom \
 
81
      --template="#define VERSION_INFO \"Project 1.2.3 (r{revno})\"\n" \
 
82
      > version_info.h
 
83
 
 
84
where the ``{revno}`` will be replaced by the revision number of the
 
85
working tree.  (If the example above doesn't work on your OS, try
 
86
entering the command all on one line.) For more information on the
 
87
variables that can be used in templates, see `Version Info`_ in the
 
88
Bazaar User Reference.
 
89
 
 
90
.. _Version Info: ../user-reference/index.html#version-info
 
91
 
 
92
Predefined formats for dumping version information in specific languages
 
93
are currently in development. Please contact us on the mailing list about
 
94
your requirements in this area.
 
95
 
 
96
Check clean
 
97
-----------
47
98
 
48
99
Most information about the contents of the project can be cheaply
49
100
determined by just reading the revision entry. However, it can be useful
53
104
set the ``clean`` flag in ``version_info``, as well as set entries in
54
105
``file_revisions`` as ``modified`` where appropriate.
55
106
 
56
 
.. 
 
107
..
57
108
   vim: tw=74 ft=rst spell spelllang=en_us