/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/overview.txt

  • Committer: Ian Clatworthy
  • Date: 2007-11-14 03:50:56 UTC
  • mto: (3054.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 3055.
  • Revision ID: ian.clatworthy@internode.on.net-20071114035056-72l6odzpby4bcmub
First cut at new look User Guide including chapters 1 and 2

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 <integrating.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
 
Core classes
17
 
############
18
 
 
19
 
Transport
20
 
=========
21
 
 
22
 
The ``Transport`` layer handles access to local or remote directories.
23
 
Each Transport object acts as a logical connection to a particular
24
 
directory, and it allows various operations on files within it.  You can
25
 
*clone* a transport to get a new Transport connected to a subdirectory or
26
 
parent directory.
27
 
 
28
 
Transports are not used for access to the working tree.  At present
29
 
working trees are always local and they are accessed through the regular
30
 
Python file I/O mechanisms.
31
 
 
32
 
Filenames vs URLs
33
 
-----------------
34
 
 
35
 
Transports work in terms of URLs.  Take note that URLs are by definition
36
 
only ASCII - the decision of how to encode a Unicode string into a URL
37
 
must be taken at a higher level, typically in the Store.  (Note that
38
 
Stores also escape filenames which cannot be safely stored on all
39
 
filesystems, but this is a different level.)
40
 
 
41
 
The main reason for this is that it's not possible to safely roundtrip a
42
 
URL into Unicode and then back into the same URL.  The URL standard
43
 
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
44
 
doesn't say how those bytes represent non-ASCII characters.  (They're not
45
 
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
46
 
 
47
 
For example, if the user enters the URL ``http://example/%e0``, there's no
48
 
way to tell whether that character represents "latin small letter a with
49
 
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2,
50
 
or malformed UTF-8.  So we can't convert the URL to Unicode reliably.
51
 
 
52
 
Equally problematic is if we're given a URL-like string containing
53
 
(unescaped) non-ASCII characters (such as the accented a).  We can't be
54
 
sure how to convert that to a valid (i.e. ASCII-only) URL, because we
55
 
don't know what encoding the server expects for those characters.
56
 
(Although it is not totally reliable, we might still accept these and
57
 
assume that they should be put into UTF-8.)
58
 
 
59
 
A similar edge case is that the URL ``http://foo/sweet%2Fsour`` contains
60
 
one directory component whose name is "sweet/sour".  The escaped slash is
61
 
not a directory separator, but if we try to convert the URL to a regular
62
 
Unicode path, this information will be lost.
63
 
 
64
 
This implies that Transports must natively deal with URLs.  For simplicity
65
 
they *only* deal with URLs; conversion of other strings to URLs is done
66
 
elsewhere.  Information that Transports return, such as from ``list_dir``,
67
 
is also in the form of URL components.
68
 
 
69
 
 
70
 
WorkingTree
71
 
===========
72
 
 
73
 
A workingtree is a special type of Tree that's associated with a working
74
 
directory on disk, where the user can directly modify the files. 
75
 
 
76
 
Responsibilities:
77
 
 
78
 
 * Maintaining a WorkingTree on disk at a file path.
79
 
 * Maintaining the basis inventory (the inventory of the last commit done)
80
 
 * Maintaining the working inventory.
81
 
 * Maintaining the pending merges list.
82
 
 * Maintaining the stat cache.
83
 
 * Maintaining the last revision the working tree was updated to.
84
 
 * Knows where its Branch is located.
85
 
 
86
 
Dependencies:
87
 
 
88
 
 * a Branch
89
 
 * an MutableInventory
90
 
 * local access to the working tree
91
 
 
92
 
Branch
93
 
======
94
 
 
95
 
A Branch is a key user concept - its a single line of history that one or
96
 
more people have been committing to. 
97
 
 
98
 
A Branch is responsible for:
99
 
 
100
 
 * Holding user preferences that are set in a Branch.
101
 
 * Holding the 'tip': the last revision to be committed to this Branch. (And the revno of that revision.)
102
 
 * Knowing how to open the Repository that holds its history.
103
 
 * Allowing write locks to be taken out to prevent concurrent alterations to the branch.
104
 
 
105
 
Depends on:
106
 
 * URL access to its base directory.
107
 
 * A Transport to access its files.
108
 
 * A Repository to hold its history.
109
 
 
110
 
Repository
111
 
==========
112
 
 
113
 
Repositories store committed history: file texts, revisions, inventories,
114
 
and graph relationships between them.  A repository holds a bag of
115
 
revision data that can be pointed to by various branches:
116
 
 
117
 
 * Maintains storage of various history data at a URL:
118
 
   * Revisions (Must have a matching inventory)
119
 
   * Digital Signatures
120
 
   * Inventories for each Revision. (Must have all the file texts available).
121
 
   * File texts
122
 
 
123
 
 * Synchronizes concurrent access to the repository by different
124
 
   processes.  (Most repository implementations use a physical 
125
 
   mutex only for a short period, and effectively support multiple readers
126
 
   and writers.)
127
 
 
128
 
Stacked Repositories
129
 
--------------------
130
 
 
131
 
A repository can be configured to refer to a list of "fallback"
132
 
repositories.  If a particular revision is not present in the original
133
 
repository, it refers the query to the fallbacks.
134
 
 
135
 
Compression deltas don't span physical repository boundaries.  So the
136
 
first commit to a new, empty repository with fallback repositories will
137
 
store a full text of the inventory, and of every new file text.
138
 
 
139
 
At runtime, repository stacking is actually configured by the branch, not
140
 
the repository.  So doing ``a_bzrdir.open_repository()``
141
 
gets you just the single physical repository, while
142
 
``a_bzrdir.open_branch().repository`` gets one configured with a stacking.
143
 
Therefore, to permanently change the fallback repository stored on disk,
144
 
you must use ``Branch.set_stacked_on_url``.
145
 
 
146
 
Changing away from an existing stacked-on URL will copy across any
147
 
necessary history so that the repository remains usable.
148
 
 
149
 
A repository opened from an HPSS server is never stacked on the server
150
 
side, because this could cause complexity or security problems with the
151
 
server acting as a proxy for the client.  Instead, the branch on the
152
 
server exposes the stacked-on URL and the client can open that.
153
 
 
154
 
 
155
 
..
156
 
   vim: ft=rst tw=74 ai