smcv / bmap-tools Goto Github PK

Summary
~~~~~~~

The bmap-tools project implements bmap-related tools and API modules. The
entire project is written in python, and requires python 2.7+.

Currently the main user of this project is Tizen IVI, but the project is
generic and can be used everywhere, when dealing with raw images.

The project author and maintainer is Artem Bityutskiy <[email protected]>.
Please, feel free to contact me if you have questions.

The project is documented here:
https://source.tizen.org/documentation/reference/bmaptool

The project mailing list is (no need to subscribe to post there):
[email protected]

Mailing list archives:
http://lists.infradead.org/pipermail/bmap-tools/

Subscribe here:
http://lists.infradead.org/mailman/listinfo/bmap-tools

The project git is here:
https://github.com/01org/bmap-tools.git

Signed release tarballs are available here:
ftp://ftp.infradead.org/pub/bmap-tools/

Packages for various distributions are available here:
* The latest release: http://download.tizen.org/tools/latest-release/
* The latest pre-release: http://download.tizen.org/tools/pre-release/
* Older releases: http://download.tizen.org/tools/archive

Please, contribute by sending patches to the mailing list, feel free to CC
me: Artem Bityutskiy <[email protected]>

The project structure
~~~~~~~~~~~~~~~~~~~~~

--------------------------------------------------------------------------------
| - bmaptool             | A tools to create bmap and copy with bmap. Based    |
|                        | on the 'BmapCreate.py' and 'BmapCopy.py' modules.   |
| - setup.py             | A script to turn the entire bmap-tools project      |
|                        | into a python egg.                                  |
| - setup.cfg            | contains a piece of nose tests configuration        |
| - .coveragerc          | lists files to include into test coverage report    |
| - TODO                 | Just a list of things to be done for the project.   |
| - make_a_release.sh    | Most people may ignore this script. It is used by   |
|                        | maintainer when creating a new release.             |
| - tests/               | Contains the project unit-tests.                    |
|   | - test_api_base.py | Tests the base API modules: 'BmapCreate.py' and     |
|   |                    | 'BmapCopy.py'.                                      |
|   | - test_filemap.py  | Tests the 'Filemap.py' module.                      |
|   | - test_compat.py   | Tests that new BmapCopy implementations support old |
|   |                    | bmap formats, and old BmapCopy implementations      |
|   |                    | support new compatible bmap fomrats.                |
|   | - helpers.py       | Helper functions shared between the unit-tests.     |
|   | - test-data/       | Data files for the unit-tests                       |
|   | - oldcodebase/     | Copies of old BmapCopy implementations for bmap     |
|   |                    | format forward-compatibility verification.          |
| - bmaptools/           | The API modules which implement all the bmap        |
|   |                    | functionality.                                      |
|   | - BmapCreate.py    | Creates a bmap for a given file.                    |
|   | - BmapCopy.py      | Implements copying of an image using its bmap.      |
|   | - Filemap.py       | Allows for reading files' block map.                |
|   | - BmapHelpers.py   | Just helper functions used all over the project.    |
|   | - TransRead.py     | Provides a transparent way to read various kind of  |
|   |                    | files (compressed, etc)                             |
| - debian/*             | Debian packaging for the project.                   |
| - packaging/*          | RPM packaging (Fedora & OpenSuse) for the project.  |
--------------------------------------------------------------------------------

How to run unit tests
~~~~~~~~~~~~~~~~~~~~~

Just install the 'nose' python test framework and run the 'nosetests' command in
the project root directory. If you want to see tests coverage report, run
'nosetests --with-coverage'.

Branches and releases
~~~~~~~~~~~~~~~~~~~~~

The project uses the following git branches:
  1. devel - here we do all the development, so this branch contains the latest
     code. Things may be broken in this branch, although we do not commit
     anything before it passes the unit-tests. But of course, the unit-tests
     have limited coverage. Anyway, do not use this branch unless you are a
     developer or you know what you are doing.
  2. master - we do not use this branch for anything but pointing to the latest
     release. This means that you may safely take this branch and be sure this
     is the latest stable code.
  3. release-x.0 - pre-releases or releases or bug-fix releases of version "x".

Let's take an example. When we start developing the 'bmap-tools' project from
scratch, and have the first version 1.0-rc1 which somehow works, we create the
'release-1.0' branch. The idea is that this branch will eventually contain the
first bmap-tools release version 1.0. But at the moment it contains the
pre-release version 0.1. As we move forward, we cut pre-releases
1.0-rc2, 1.0-rc3..., 1.0-rc7, and so on. They are all published in the
'release-1.0' branch. And of course, the 'master' branch points to the latest
release (same as release candidate, rc).

Then at some point we finally release the first 'bmap-tools' version 1.0. No
more features are added to the 1.0 release. At the same time we continue
developing in the 'devel' branch and add major features for the next '2.0'
release. We create the 'release-2.0' branch, and publish 2.0 pre-releases
there: 2.0-rc1, 2.0-rc2, etc.

Meanwhile, users report brown-paperbag flaws in bmap-tools-1.0. We fix the
issues, and publish bug-fix releases: 1.1, 1.2, etc. They are also published in
the 'release-1.0' branch. The 'master' branch points to the latest 2.0
release, though.

Credits
~~~~~~~

* Ed Bartosh <[email protected]> for helping me with learning python
  (this is my first python project) and working with the Tizen IVI
  infrastructure. Ed also implemented the packaging.
* Alexander Kanevskiy <[email protected]> and
  Kevin Wang <[email protected]> for helping with integrating this stuff
  to the Tizen IVI infrastructure.
* Simon McVittie <[email protected]> for improving Debian
  packaging and fixing bmaptool.