buildframework/helium/doc/src/architecture.rst
author andy simpson <andrews@symbian.org>
Fri, 30 Jul 2010 15:14:33 +0100
changeset 652 311511800c67
parent 645 b8d81fa19e7d
permissions -rw-r--r--
Add export for s60ibymacros.pm (re-applies missing part of fix for Bug 2901
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
     1
..  ============================================================================ 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
     2
    Name        : architecture.rst
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
     3
    Part of     : Helium 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
     4
    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
     5
    Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
     6
    All rights reserved.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
     7
    This component and the accompanying materials are made available
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
     8
    under the terms of the License "Eclipse Public License v1.0"
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
     9
    which accompanies this distribution, and is available
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    10
    at the URL "http://www.eclipse.org/legal/epl-v10.html".
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    11
    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    12
    Initial Contributors:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    13
    Nokia Corporation - initial contribution.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    14
    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    15
    Contributors:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    16
    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    17
    Description:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    18
    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    19
    ============================================================================
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    20
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    21
###########################
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    22
Helium Architecture
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    23
###########################
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    24
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    25
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    26
  module: Helium Architecture
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    27
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    28
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    29
.. contents::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    30
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    31
Introduction
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    32
============
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    33
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    34
This is a overview of the Helium toolkit and its dependencies as a stack.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    35
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    36
.. raw:: html
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    37
   :file: helium_overview.html
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    38
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    39
   
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    40
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    41
  single: Architectural Principles
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    42
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    43
Architectural principles
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    44
========================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    45
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    46
**Favour reusing existing software over writing new code.** There is a lot of useful open-source software available. If the license is sufficiently open it is better to use what exists. Development of new features should check for any existing software that may fulfill some or all of the implementation requirements.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    47
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    48
**Favour reusable libraries over standalone scripts.** Object-orientated programming and the development of libraries encourages reusability, reduced maintenance and higher quality.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    49
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    50
**Develop unit tests for testing the libraries.** Unit testing is important for regression testing and for agile development within a team. A developer can make changes and have confidence that no functionality has broken by running the unit tests.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    51
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    52
**Prefer platform independence.** The selection of tools and the development of libraries and scripts is done in a way that maximises independence from the underlying OS or hardware platform. Where specific dependencies are required they are configurable. Shell commands should be restricted to the set supported by the Unix Utils package on Windows, to ensure compatibility between Linux and Windows.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    53
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    54
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    55
  single: Archtectural References
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    56
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    57
References
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    58
----------
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    59
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    60
* The Pragmatic Programmer, Andrew Hunt and David Thomas. See the `list of tips`_.
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    61
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    62
.. _`list of tips` : http://www.pragmaticprogrammer.com/ppbook/extracts/rule_list.html
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    63
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    64
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    65
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    66
  single: Architectural Practices
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    67
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    68
Practices
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    69
=========
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    70
645
b8d81fa19e7d helium_12.0.0-63b64366f9cf
wbernard
parents: 587
diff changeset
    71
Files created in Ant, Perl, Python or XML syntax must follow the `Style guide <development/coding_conventions.html>`_.
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    72
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    73
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    74
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    75
  single: Architectural Configuration
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    76
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    77
Configuration
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    78
=============
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    79
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
    80
XML is recommended for defining configuration files. Ant configuration types and tasks should be used where logical. If a more structured configuration is needed then a custom XML schema can be defined. Existing schemas should be reused where possible.
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    81
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    82
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    83
  single: APIs
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    84
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    85
APIs 
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    86
=========
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    87
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    88
See the reference API documentation:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    89
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    90
* `Helium API`_
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    91
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    92
.. _`Helium API` : api/helium/index.html
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    93
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    94
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    95
  single: Tools and scripts locations
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    96
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    97
Tools and scripts locations
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    98
===========================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
    99
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   100
All tools used by Helium (which means called by Ant at some point during a build sequence, directly or indirectly) come from one of these locations:
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   101
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
   102
* Inside ``/helium/tools``. Content is generally developed or imported by the Helium team and is our responsibility. We strive to test it using unit tests where possible and general build execution. It should follow Helium coding guidelines. This may be libraries closely integrated with Ant, or standalone tools called by Ant like iCreatorDP.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
   103
* Inside ``/helium/external``. These are tools provided by an external party, which could be open source projects or other teams in Nokia. Updates are the responsibility of the maintainer. Typically Helium developers will import the updates, but if agreed the supplier might also directly make the update. If the content is currently provided as a Synergy project it is desirable to simply use releases of that.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
   104
* Inside ``/epoc32``. This covers the Symbian toolchain, iMaker, etc. At the point where the tool is needed it should have been exported into /epoc32.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
   105
* Already Installed. All language runtimes such as Java, Perl and Python.
1
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   106
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   107
.. index::
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   108
  single: Dependency Diagram
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   109
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   110
Dependency Diagram
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   111
==================
be27ed110b50 Bringing in Helium, imaker and cmaker
Alex Gilkes <alex.gilkes@nokia.com>
parents:
diff changeset
   112
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents: 1
diff changeset
   113
.. image:: dependencies.grph.png