..  ============================================================================ 
    Name        : blocks.rst
    Part of     : Helium 
    
    Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
    All rights reserved.
    This component and the accompanying materials are made available
    under the terms of the License "Eclipse Public License v1.0"
    which accompanies this distribution, and is available
    at the URL "http://www.eclipse.org/legal/epl-v10.html".
    
    Initial Contributors:
    Nokia Corporation - initial contribution.
    
    Contributors:
    
    Description:
    
    ============================================================================

.. index::
  module: Blocks

======
Blocks
======

.. contents::

.. _`Blocks-Intro-label`:

Blocks Introduction
====================

Blocks is a packaging framework, which allows you to create bundles 
with interdependencies (like rpm or deb packages) base on the outcome of the build.


Enabling Blocks input generation
================================

The input generation consists in gathering data from build steps throughout the build to allow the generation
of the future bundle. Not all the steps are supported, so the build engineer must keep in mind that custom
exports or modification of the binaries after a controlled build step might lead to bundles with inconsistent content.
 
In order to enable blocks input generation you simply need to define the **blocks.enabled** property to true. Intermediate 
configuration file will be generated under **blocks.config.dir**.

e.g::
   
   hlm -Dblocks.enabled=true....


Currently supported steps are:
 * SBSv2 compilation
 * Configuration export using cMaker (only if cmaker-what is called)
 * ROM image creation


Bundle generation
=================

Once the data have been gathered during the build, it is then possible to create bundles. To do so you need to call the 
**blocks-create-bundles** target. Generated bundle will be created under **blocks.bundle.dir**.

e.g::
   
   hlm -Dblocks.enabled=true .... blocks-create-bundles
   

Blocks workspace management with Helium 
=======================================

Helium allows you to use any build environment as Blocks workspace. The :hlm-t:`blocks-create-workspace` will handle the
automatic creation of workspace base on the current build.drive used. If the current build.drive represent an
already existing workspace then it will reuse it. The :hlm-p:blocks.workspace.id property will contain the Blocks workspace
id. Also when new workspace is created some repositories can be automatically added using the **blocks.repositories.id** reference
to an hlm:blocksRepositorySet object.

::
   
   <hlm:blocksRepositorySet id="blocks.repositories.id">
       <repository name="test-repo" url="file:E:\my-repo" />
   </hlm:blocksRepositorySet>
   


Installing bundles
==================
The :hlm-t:`blocks-install-bundles` target will allow you to install packages under the workspace, to do so, you can configure
the following references using patternset:

::
   
   <patternset id="blocks.bundle.filter.id">
       <include name="some.pkg.name.*" /> 
       <exclude name="some.other.pkg.name.*" /> 
   </patternset>

   <patternset id="blocks.group.filter.id">
       <include name="some.pkg.name.*" /> 
       <exclude name="some.other.pkg.name.*" /> 
   </patternset>
   
      
The **blocks.bundle.filter.id** patternset will allow you to filter bundles based on their name. And **blocks.bundle.filter.id** patternset will allow you
to install group selected group of bundles.

Finally the workspace can be updated using the :hlm-t:`blocks-update-bundles` target.