Picked up some text from the old documentation branch. Still mostly out of date.

Jörg Knobloch 2 years ago
parent 0b8a2454a7
commit ec5e43dd20

@ -1,5 +1,24 @@
## The `window` object
# Guide to the code
The control flow starts from `chrome/bootstrap.js` where we specify
window scripts like `pepmessengercompose.js` and
`pepmsghdrview.js`. These scripts are executed when Thunderbird opens
a window with the matching type.
These "window scripts" are in in `chrome/content` like most of the
code. When executed they import other modules with
`ChromeUtils.import`, passing the window and other global objects if
needed. Outside of this context we cannot assume that `window` is
The three-pane window is always running when Thunderbird is running,
so its `pepmsghdrview.js` script performs most of the application
initialisation. One of the main objects to be initialised is the
controller within `chrome/content/p4tb.js`.
# The `window` object
In `bootstrap.js` we subscribe to notifications from a `ww` service
that calls a `paint` method when the `window` object is globally
@ -10,14 +29,99 @@ it. Outside of this context we cannot assume that `window` is
accessible. An `unpaint` notification will be sent when the window is
## pEpController and `p4tb.js`
The `pEpController` is a module defined in
`chrome/content/modules/pEp.js` and is meant to be independent from
Thunderbird. Within `p4tb.js`, the controller gets augmented with
Thunderbird-specific logic.
`p4tb.js` also contains most of the initialisation logic. There the
server gets a `detectJsonAdapter` which populates the
`server.connectionInfo` on initialisation.
Note that this initialisation sequence is confined to the window where
the script has run, so it's executed again for every message
composition window when the matching `pepmessengercompose.js` script
is executed.
## Types of modules
Above we mentioned the `pEpController` module. Here we have mainly two
types of modules:
- `ChromeUtils` modules
- `ChromeUtils` & Node modules
Most files in `chrome/content` define a module of the first type. The
files in `chrome/content/modules` are `ChromeUtils` _and_ Node
modules, so they can be tested with our unit tests.
Our Node modules cannot import other Node modules because then they
wouldn't work as `ChromeUtils` modules. These modules can be imported
once and that's it. They can be combined with each other using
dependency injection.
## Encryption & Decryption
Encryption and decryption are performed via components and factories
defined in `pEpMimeEncrypt.js` and `pEpMimeDecrypt.js` (branch
`P4TB-43-2` to be merged).
We define component objects and wrap them with factories that get
registered on startup and deregistered on teardown. You might want to
deregister factories for testing purposes, since only one factory can
be registered for every component id.
Component objects are created in isolation when some events happen,
for example the encryption component is created when there is an
outgoing message. Since they have this ad-hoc, isolated lifecycle,
communication between our components and our views is not
# Other notes
## Environment setup
We suggest to use [different
one for your regular mail use and one for extension development.
Testing can be done using one of the [test accounts (need VPN
## Relevant entry points to the engine code
Most of the extension code is written under the assumption that the
extension developer can read the engine code as a form of
documentation and keep the extension synchronised with the engine's
(and adapter's) interfaces.
Many interfaces are defined in the following engine's files:
- `pEpEngine.h`
- `message_api.h`
- `message.h`
- `pEp_internal.h`
After that, grep is your friend/enemy (`darthmama`'s quote)
## Adapter
The extension connects to the JSON adapter server using a token which
is found in `~/.pEp/json-token`. The whole purpose of the token is to
be sure that the client runs with the same user rights than the server
(`Roker`'s quote).
## Updating the options
When we want to change the plugin preferences we can do so by
modifying three areas in the code:
modifying different areas in the code:
- `options.xul` the markup, here you define the identifier for the option that will be used also elsewhere
- `prefsFactory.js` update getter and setter functions corresponding to the option and the default value
- `options.js` update `addAll`, the window load handler, the dialogAccept handler
- `bootstrap.js` update the defaults
## Compat and Prefs

@ -1,12 +1,20 @@
# p≡p for Thunderbird
Using docker
# p≡p for Thunderbird
```docker build -t <image_tag> . && docker run -v build:/usr/src/app/build <image_tag> ```
This is a Thunderbird extension providing p≡privacy to your mail. It
relies on the [p≡p JSON adapter][adapter] to access the key
management, synchronisation and automation logic provided by the p≡p
## How To Build
Using bash
Just run `make` to build from the current source, producing a file in
`build/p4t.xpi` that can be installed from Thunderbird's add-ons
manager page clicking on "Install from file". For information about
building and running the engine adapter see [its repo][adapter].
```cd addon ; zip -r ../build/pEp4Tb@pEp.security.xpi . ; cd ..```
## Check syntax statically
@ -38,3 +46,10 @@ To run tests first is needed to install all dependencies
npm run test
npm run linttest
## More info
Check the `DEVELOPMENT.md` file here for a collection of development
notes. See also [our dev wiki](https://dev.pep.security/thunderbird/).
[adapter]: https://pep.foundation/dev/repos/pEpJSONServerAdapter "JSON Adapter"