← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/overview.txt

  • Committer: Andrew Bennetts
  • Date: 2010-10-08 08:15:14 UTC
  • mto: This revision was merged to the branch mainline in revision 5498.
  • Revision ID: andrew.bennetts@canonical.com-20101008081514-dviqzrdfwyzsqbz2
Split NEWS into per-release doc/en/release-notes/bzr-*.txt

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/overview.txt
 
1
=============================
 
2
Bazaar Architectural Overview
 
3
=============================
 
4
 
 
5
This document describes the key classes and concepts within Bazaar.  It is
 
6
intended to be useful to people working on the Bazaar codebase, or to
 
7
people writing plugins.  People writing plugins may also like to read the 
 
8
guide to `Integrating with Bazaar <integration.html>`_ for some specific
 
9
recipes.
 
10
 
 
11
If you have any questions, or if something seems to be incorrect, unclear
 
12
or missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write
 
13
to the Bazaar mailing list.  
 
14
 
 
15
 
 
16
Using bzrlib
 
17
############
 
18
 
 
19
Within bzr
 
20
==========
 
21
 
 
22
When using bzrlib within the ``bzr`` program (for instance as a bzr
 
23
plugin), bzrlib's global state is already available for use.
 
24
 
 
25
From outside bzr
 
26
================
 
27
 
 
28
To use bzrlib outside of ``bzr`` some global state needs to be setup.
 
29
bzrlib needs ways to handle user input, passwords, a place to emit
 
30
progress bars, logging setup appropriately for your program. The easiest
 
31
way to set all this up in the same fashion ``bzr`` does is to call
 
32
``bzrlib.initialize``. This returns a context manager within which bzrlib
 
33
functions will work correctly. See the pydoc for ``bzrlib.initialize`` for
 
34
more information. In Python 2.4 the ``with`` keyword is not supported and
 
35
so you need to use the context manager manually::
 
36
 
 
37
  # This sets up your ~/.bzr.log, ui factory and so on and so forth. It is
 
38
  # not safe to use as a doctest.
 
39
  library_state = bzrlib.initialize()
 
40
  library_state.__enter__()
 
41
  try:
 
42
      pass
 
43
      # do stuff here
 
44
  finally:
 
45
      library_state.__exit__(None, None, None)
 
46
 
 
47
 
 
48
Core classes
 
49
############
 
50
 
 
51
Transport
 
52
=========
 
53
 
 
54
The ``Transport`` layer handles access to local or remote directories.
 
55
Each Transport object acts as a logical connection to a particular
 
56
directory, and it allows various operations on files within it.  You can
 
57
*clone* a transport to get a new Transport connected to a subdirectory or
 
58
parent directory.
 
59
 
 
60
Transports are not used for access to the working tree.  At present
 
61
working trees are always local and they are accessed through the regular
 
62
Python file I/O mechanisms.
 
63
 
 
64
Filenames vs URLs
 
65
-----------------
 
66
 
 
67
Transports work in terms of URLs.  Take note that URLs are by definition
 
68
only ASCII - the decision of how to encode a Unicode string into a URL
 
69
must be taken at a higher level, typically in the Store.  (Note that
 
70
Stores also escape filenames which cannot be safely stored on all
 
71
filesystems, but this is a different level.)
 
72
 
 
73
The main reason for this is that it's not possible to safely roundtrip a
 
74
URL into Unicode and then back into the same URL.  The URL standard
 
75
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
 
76
doesn't say how those bytes represent non-ASCII characters.  (They're not
 
77
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
 
78
 
 
79
For example, if the user enters the URL ``http://example/%e0``, there's no
 
80
way to tell whether that character represents "latin small letter a with
 
81
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2,
 
82
or malformed UTF-8.  So we can't convert the URL to Unicode reliably.
 
83
 
 
84
Equally problematic is if we're given a URL-like string containing
 
85
(unescaped) non-ASCII characters (such as the accented a).  We can't be
 
86
sure how to convert that to a valid (i.e. ASCII-only) URL, because we
 
87
don't know what encoding the server expects for those characters.
 
88
(Although it is not totally reliable, we might still accept these and
 
89
assume that they should be put into UTF-8.)
 
90
 
 
91
A similar edge case is that the URL ``http://foo/sweet%2Fsour`` contains
 
92
one directory component whose name is "sweet/sour".  The escaped slash is
 
93
not a directory separator, but if we try to convert the URL to a regular
 
94
Unicode path, this information will be lost.
 
95
 
 
96
This implies that Transports must natively deal with URLs.  For simplicity
 
97
they *only* deal with URLs; conversion of other strings to URLs is done
 
98
elsewhere.  Information that Transports return, such as from ``list_dir``,
 
99
is also in the form of URL components.
 
100
 
 
101
 
 
102
WorkingTree
 
103
===========
 
104
 
 
105
A workingtree is a special type of Tree that's associated with a working
 
106
directory on disk, where the user can directly modify the files. 
 
107
 
 
108
Responsibilities:
 
109
 
 
110
 * Maintaining a WorkingTree on disk at a file path.
 
111
 * Maintaining the basis inventory (the inventory of the last commit done)
 
112
 * Maintaining the working inventory.
 
113
 * Maintaining the pending merges list.
 
114
 * Maintaining the stat cache.
 
115
 * Maintaining the last revision the working tree was updated to.
 
116
 * Knows where its Branch is located.
 
117
 
 
118
Dependencies:
 
119
 
 
120
 * a Branch
 
121
 * an MutableInventory
 
122
 * local access to the working tree
 
123
 
 
124
Branch
 
125
======
 
126
 
 
127
A Branch is a key user concept - its a single line of history that one or
 
128
more people have been committing to. 
 
129
 
 
130
A Branch is responsible for:
 
131
 
 
132
 * Holding user preferences that are set in a Branch.
 
133
 * Holding the 'tip': the last revision to be committed to this Branch. (And the revno of that revision.)
 
134
 * Knowing how to open the Repository that holds its history.
 
135
 * Allowing write locks to be taken out to prevent concurrent alterations to the branch.
 
136
 
 
137
Depends on:
 
138
 * URL access to its base directory.
 
139
 * A Transport to access its files.
 
140
 * A Repository to hold its history.
 
141
 
 
142
Repository
 
143
==========
 
144
 
 
145
Repositories store committed history: file texts, revisions, inventories,
 
146
and graph relationships between them.  A repository holds a bag of
 
147
revision data that can be pointed to by various branches:
 
148
 
 
149
 * Maintains storage of various history data at a URL:
 
150
 
 
151
   * Revisions (Must have a matching inventory)
 
152
   * Digital Signatures
 
153
   * Inventories for each Revision. (Must have all the file texts available).
 
154
   * File texts
 
155
 
 
156
 * Synchronizes concurrent access to the repository by different
 
157
   processes.  (Most repository implementations use a physical 
 
158
   mutex only for a short period, and effectively support multiple readers
 
159
   and writers.)
 
160
 
 
161
Stacked Repositories
 
162
--------------------
 
163
 
 
164
A repository can be configured to refer to a list of "fallback"
 
165
repositories.  If a particular revision is not present in the original
 
166
repository, it refers the query to the fallbacks.
 
167
 
 
168
Compression deltas don't span physical repository boundaries.  So the
 
169
first commit to a new, empty repository with fallback repositories will
 
170
store a full text of the inventory, and of every new file text.
 
171
 
 
172
At runtime, repository stacking is actually configured by the branch, not
 
173
the repository.  So doing ``a_bzrdir.open_repository()``
 
174
gets you just the single physical repository, while
 
175
``a_bzrdir.open_branch().repository`` gets one configured with a stacking.
 
176
Therefore, to permanently change the fallback repository stored on disk,
 
177
you must use ``Branch.set_stacked_on_url``.
 
178
 
 
179
Changing away from an existing stacked-on URL will copy across any
 
180
necessary history so that the repository remains usable.
 
181
 
 
182
A repository opened from an HPSS server is never stacked on the server
 
183
side, because this could cause complexity or security problems with the
 
184
server acting as a proxy for the client.  Instead, the branch on the
 
185
server exposes the stacked-on URL and the client can open that.
 
186
 
 
187
 
 
188
..
 
189
   vim: ft=rst tw=74 ai