# Opera Core from the outside

$Id$

This document describes the common controlled API to the core code of Opera. Its intended audience is members of the Opera engineering department.

## The Core API defines the Opera core

The Core API consists of a description of what the core does, plus code to access or activate that functionality. (See a separate section below for many more details.) Its purpose is to make most platform and customer requirements to the core visible in three ways:

- as code that is visible in the API;
- as core-internal features that can be turned on and off in a configuration file; or
- as operational requirements on the core code.

In particular, platform and customer requirements are no longer met by platform-group authored and owned code embedded inside the core code. Instead, to the greatest extent possible the requirements on the core are explicit, so that the core code does not meet them by accident, but by design; and all core code is controlled by the core group.

## Block diagram

The following block diagram shows our working model of the view of the Core code from the outside. It is probably not complete, but it covers a large number of cases. Explanations to the various boxes follow below.

          DreamWeaver,         +-------------+   +---GUI---+
          Teleca UI, ... --->  |Customer code|   |  Plat.  |
                               +-------------+   |   UI    |
          Linux SDK,           +--Opera API--+   |  code   |
          OperaBridge, ----->  |Cust adaption|   |         |
          MacroMedia API, ...  +-------------+   +---------+

           +---Core utils---+-----------Core API upward---------+----Featurettes---+
           | +-----------+  | +-------------------------------+ | +-----------+    |
           | |    Util   |  | |  Prefs        WindowCommander | | | JsPlugins ==========> customer code
           | +-----------+  | +-------------------------------+ | +-----------+    |
           |                |                                   | +-----------+    |
           |                |                                   | |    JVM    ==========> (Sun) JVM
           |                |                                   | +-----------+    |
           |                |                                   | +-----------+    |
           |                |       Contents of core code       | | NSPlugins ==========> 3rd party plugins
           |                |        may be controlled by       | +-----------+    |
           |                |       settings of FEATURE_*       | +-----------+    |
           |                |                                   | | ES Voice  ==========> IBM code
           |                |                                   | +-----------+    |
           |                |                                   | +-----------+    |
           |                |                                   | |  VoiceAPI ==========> IBM code
           |                |                                   | +-----------+    |
           |                |                                   | +-----------+    |
           |                | +-------------------------------+ | |  MailGlue ==========> M2
           |                | | Prefs       PortingInterfaces | | +-----------+    |
           |                | +-------------------------------+ |       ...        |
           +----------------+---------Core API downward---------+------------------+

                            +-----------------------------------+
                            |        Platform support code      |
                            +-----------------------------------+

Core
  The big box in the middle (with external APIs represented by "Core Utils", "Core API upward", "Core API downward", and "Featurettes") represents the core code.
Major interfaces
  Core exports an API upward to the user interface, this consists of WindowCommander and Preferences. It also exports an API downward to the platform support code, this consists of PortingInterfaces (which must be instantiated) and Preferences.
Auxiliary interfaces ("Featurettes")
  Core also exports special APIs directly to "customer" code, for example, JavaScript plugins and the Voice APIs. These featurettes are not related to porting Opera to a new platform but rather allow customer add-ins.
Utility code
  In addition, both kinds of platform code may rely on the Core Utilities functionality, a random collection of support code that does not have anything to do with browsing per se but may provide string, numeric, unicode, etc functionality.
Features
  The functionality in the Core, and sometimes aspects of the Core APIs, are controlled through a feature system that enable and disable various parts of the Core code.

It is probable that not all of Opera as it is now is representable in this architecture, so the drawing may change (or Opera may change). One example is Opera initialization: it does not obviously belong in WindowCommander or PortingInterfaces; and initialization order differs on different platforms, with platform code sometimes being initialized after some core pieces are ready but before others.

## What is really the Core API?

It is the code we produce that we sell, but the core API is mostly not about code. Instead it is about structures that support the development of a reliable product, or in this case, a reliable core component.

The Core API consists of at least these following parts. Note that one can make each of these arbitrarily complex; we aim to make them light-weight. (We have code to write.)

### Interfaces: WindowCommander, Prefs, Util, and Featurettes.

- Classes, methods, and constants. Defined in header files. Documentation for these aspects is covered by the following section.
- Supported Core FEATURES. Defined in core/vfunc.h and documented in core/vfunc.txt.
- Assumptions the core code makes about the platform. These are things that can be fixed if they turn out not to be true, but doing so may require substantial work.

### Documentation

- Metadocumentation and a map. You're reading it.
- Interface documentation. Mainly this is split into two parts:
  - Structural documentation is textual (HTML) and graphical (UML). Documentation is kept with the code and can/will be extracted onto the intranet automatically.
  - Each class, method, and constant is also documented doxygen-style in the code. This too can/will be extracted onto the intranet.
- Tutorials, examples, FAQs. Some of this may be placed on the Wiki.
- Design principles.

### Non-interface aspects of the core code

- Envelope of change. These are the hard architectural constraints of the core code.
- Specifications. These are the things the core code should do or conform to that do not show up in interfaces, per se.
- Information. This could be things like lists of the compilers we know we have used; 3rd party modules we use.

### Process

- Change requests. How/when are requirements/needs communicated to the core; how do we implement them in a timely manner; etc.
- Principles for what we do.
  - One principle is that requirements are to be communicated as functional requirements, not as code. Of course, code may be enclosed as a prototype implementation, but code does not constitute a requirement.
- How to track bugs. The BTS is not a very good fit with our new module/product structure. This needs to be worked out.
- Release process. Core will become a versioned product, with bug fixes and so on.
- Support. Call +47 2416 4063, $10/minute. (Just joking.)

### Core code

- The canonical core implementation
- Selftest
- Testsuites
- Maybe dummy implementations of various interfaces to ease testing and porting