← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/overview.txt

add a clean target

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.
8
 
 
9
 
If you have any questions, or if something seems to be incorrect, unclear
10
 
or missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write
11
 
to the Bazaar mailing list.  To propose a correction or addition to this
12
 
document, send a merge request or new text to the mailing list.
13
 
 
14
 
The current version of this document is available in the file
15
 
``doc/developers/overview.txt`` in the source tree, and from 
16
 
<http://doc.bazaar-vcs.org/bzr.dev/>.
17
 
 
18
 
See also:
19
 
 
20
 
 * `Bazaar Developer Documentation Catalog <index.html>`_.
21
 
 * `Bazaar Developer Guide <../en/developer-guide/HACKING.html>`_
22
 
   (particularly the *Coding Style Guidelines* section.)
23
 
 
24
 
.. contents::
25
 
 
26
 
Essential Domain Classes
27
 
########################
28
 
 
29
 
The core domain objects within the bazaar model are:
30
 
 
31
 
* Transport
32
 
 
33
 
* Branch
34
 
 
35
 
* Repository
36
 
 
37
 
* WorkingTree
38
 
 
39
 
Transports are explained below. See http://bazaar-vcs.org/Classes/
40
 
for an introduction to the other key classes.
41
 
 
42
 
Transport
43
 
#########
44
 
 
45
 
The ``Transport`` layer handles access to local or remote directories.
46
 
Each Transport object acts as a logical connection to a particular
47
 
directory, and it allows various operations on files within it.  You can
48
 
*clone* a transport to get a new Transport connected to a subdirectory or
49
 
parent directory.
50
 
 
51
 
Transports are not used for access to the working tree.  At present
52
 
working trees are always local and they are accessed through the regular
53
 
Python file I/O mechanisms.
54
 
 
55
 
Filenames vs URLs
56
 
=================
57
 
 
58
 
Transports work in terms of URLs.  Take note that URLs are by definition
59
 
only ASCII - the decision of how to encode a Unicode string into a URL
60
 
must be taken at a higher level, typically in the Store.  (Note that
61
 
Stores also escape filenames which cannot be safely stored on all
62
 
filesystems, but this is a different level.)
63
 
 
64
 
The main reason for this is that it's not possible to safely roundtrip a
65
 
URL into Unicode and then back into the same URL.  The URL standard
66
 
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
67
 
doesn't say how those bytes represent non-ASCII characters.  (They're not
68
 
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
69
 
 
70
 
For example, if the user enters the URL ``http://example/%e0``, there's no
71
 
way to tell whether that character represents "latin small letter a with
72
 
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2,
73
 
or malformed UTF-8.  So we can't convert the URL to Unicode reliably.
74
 
 
75
 
Equally problematic is if we're given a URL-like string containing
76
 
(unescaped) non-ASCII characters (such as the accented a).  We can't be
77
 
sure how to convert that to a valid (i.e. ASCII-only) URL, because we
78
 
don't know what encoding the server expects for those characters.
79
 
(Although it is not totally reliable, we might still accept these and
80
 
assume that they should be put into UTF-8.)
81
 
 
82
 
A similar edge case is that the URL ``http://foo/sweet%2Fsour`` contains
83
 
one directory component whose name is "sweet/sour".  The escaped slash is
84
 
not a directory separator, but if we try to convert the URL to a regular
85
 
Unicode path, this information will be lost.
86
 
 
87
 
This implies that Transports must natively deal with URLs.  For simplicity
88
 
they *only* deal with URLs; conversion of other strings to URLs is done
89
 
elsewhere.  Information that Transports return, such as from ``list_dir``,
90
 
is also in the form of URL components.
91
 
 
92
 
 
93
 
Repository
94
 
##########
95
 
 
96
 
Repositories store committed history: file texts, revisions, inventories,
97
 
and graph relationships between them.
98
 
 
99
 
Stacked Repositories
100
 
====================
101
 
 
102
 
A repository can be configured to refer to a list of "fallback"
103
 
repositories.  If a particular revision is not present in the original
104
 
repository, it refers the query to the fallbacks.
105
 
 
106
 
Compression deltas don't span physical repository boundaries.  So the
107
 
first commit to a new, empty repository with fallback repositories will
108
 
store a full text of the inventory, and of every new file text.
109
 
 
110
 
At runtime, repository stacking is actually configured by the branch, not
111
 
the repository.  So doing ``a_bzrdir.open_repository()`` 
112
 
gets you just the single physical repository, while 
113
 
``a_bzrdir.open_branch().repository`` gets one configured with a stacking. 
114
 
Therefore, to permanently change the fallback repository stored on disk,
115
 
you must use ``Branch.set_stacked_on_url``.  
116
 
 
117
 
Changing away from an existing stacked-on URL will copy across any
118
 
necessary history so that the repository remains usable.
119
 
 
120
 
A repository opened from an HPSS server is never stacked on the server
121
 
side, because this could cause complexity or security problems with the
122
 
server acting as a proxy for the client.  Instead, the branch on the
123
 
server exposes the stacked-on URL and the client can open that.
124
 
 
125
 
 
126
 
..
127
 
   vim: ft=rst tw=74 ai