Skip to content
Let's Grow a Library
Branch: master
Clone or download
JohnThomson Merge pull request #3320 from BloomBooks/BL7444_UndoTestHack
Undo test hack by having relevant tests create real files (BL-7444)
Latest commit 19a97cc Jul 19, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.nuget Download and use current nuget version Jun 29, 2017
Design Fix BL-6814 Wrong capitalization on Ace by DAISY Jan 15, 2019
DistFiles Merge pull request #3251 from BloomBooks/l10n_master Jul 10, 2019
artwork BL-7025 Get Bloom Player from NPM Apr 11, 2019
build Remove dependency on bloomPlayer.js (BL-7332) Jun 28, 2019
debian Improve xchm use for viewing help on Linux (BL-7244) Jun 26, 2019
lib Allow playback of mp3 files if wav is not present (BL-6739) Dec 21, 2018
packages Revert gitkraken fail Jan 24, 2017
scanner samples book Add guidsForInstaller Apr 19, 2012
src Undo test hack by having relevant tests create real files (BL-7444) Jul 19, 2019
.editorconfig Add .xlf files to .editorconfig Apr 24, 2019
.gitattributes Treat whitespace in .tsx files the same as .ts Aug 16, 2018
.gitignore BL-7019 Send analytics from simple comprehension quiz May 9, 2019
.prettierignore Add Thema subject selection to the epub metadata dialog (BL-6173) Aug 16, 2018
Bloom.sln Publish to Androi UI via react component wired to a c# API controller Jul 12, 2017
BloomMD.mdpolicy Add shared MonoDevelop setting file and settings to solution Oct 23, 2014
BloomR#.DotSettings Add shared Visual Studio and ReSharper settings Oct 23, 2014
BloomVS.vssettings Add shared Visual Studio and ReSharper settings Oct 23, 2014
GetBuildRun.bat (in progress) moving to separate xmatter template Dec 17, 2011
LICENSE.txt Create LICENSE.txt Feb 28, 2017 BL-6559 Record by sentence or whole text mode Oct 20, 2018
crowdin.yml Update Crowdin configuration file Mar 2, 2018
environ Improve xchm use for viewing help on Linux (BL-7244) Jun 26, 2019
environ-xulrunner Fix a couple of Linux problems for version 3.8 (BL-3541) Jun 16, 2016

Let's Grow Some Libraries

Bloom Desktop is an award winning software solution to the children's book shortage among most of the world's languages. It is an application for Windows and Linux that dramatically "lowers the bar" for creating, translating, and sharing books. WIth Bloom, communities can do the work for themselves instead of depending on outsiders.

Internally, Bloom is a hybrid. It started as a c#/winforms app with an embedded browser for editing documents and an embedded Adobe Acrobat for displaying PDF outputs. It wants to grow up to be a pure react-driven offline-capable web app, perhaps with a c# backend. In its current adolescence, Bloom is hybrid of c#/web app in which the bits of the UI are gradually moving to html.

Windows Linux
Build Build Status
.net Unit tests (part of above build) Build Status

Development Process

Kanban / Bug Reports

We use YouTrack Kanban boards. Errors (via email or api) also flow into YouTrack, and we do some support from there by @mentioning users.

Continuous Build System

Each time code is checked in, an automatic build begins on our TeamCity build server, running all the unit tests. Similarly, when there is a new version of some Bloom dependency (e.g. Palaso, PdfDroplet, our fork of GeckoFX), that server automatically rebuilds Bloom. This automatic build doesn't publish a new installer, however. That kind of build is launched manually, by pressing a button on the TeamCity page. This "publish" process builds Bloom, makes and installer, rsyncs it to the distribution server, and writes out a little bit of html which the Bloom download page then displays to the user.

Building Web Source Code

Install yarn (

You'll need nodejs installed. As time goes on, the required version of nodejs changes. Bloom 4.1 (and several earlier versions of Bloom) builds with nodejs 6.10.1. Bloom 4.2 (and later versions of Bloom) builds with nodejs 8.10.0. To make this feasible, we use nvm-windows on Windows and nvm on Linux to install and manage which version of nodejs is active for the build process. To install nvm on Windows, go to nvm-windows releases and download the latest file. Unzip the downloaded file and run the nvm-setup.exe program to install nvm. Once nvm has been installed for windows, run these commands in a command window to install the needed versions of nodejs. This needs to be done only once.

nvm install 6.10.1
nvm install 8.10.0
nvm ls

To install nvm (and the needed versions of nodejs) on Linux, run these commands in a bash shell window. Again, this needs to be done only once. (The version of nvm may change over time. Check the nvm home page for exact details.)

wget -qO- | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/" ] && \. "$NVM_DIR/" # This loads nvm as a shell function
command -v nvm                                   # This should respond with "nvm"
nvm install 6.10.1
nvm install 8.10.0
nvm ls

This will build and test the Typescript, javascript, less, and pug:

cd src/BloomBrowserUI
nvm use 8.10.0    # or 6.10.1 if building Bloom 4.1 or earlier
npm install
npm run build
npm test

To help keep all of these commands straight, a shell script named is stored in the build folder (alongside the getDependencies shell scripts). It can run either on Linux or in the git bash shell on Windows. The command you type is very simple:


There are command line options to disable either the 'npm install' and 'npm test' commands if all you want to do is build. (--skip-install and --skip-test are the verbose forms of those options.)

'npm run build' is really just running some gulp scripts, defined in gulpfile.js. Note that when you're using Visual Studio, the "Task Runner Explorer" can be used to start those gulp tasks, and VS should run the "default" gulp task each time it does a build. To make it run this each time you do a "run", though, make sure you've turned off this option:

Tools:Options:Projects and Solutions:Build and Run:Only build startup projects and dependencies on Run

We use webpack for building the Typescript, running Javascript through Babel, and packing everything six top-level (apps (ugghhh)). When coding in Typescript/Javascript, then go to the src/BloomBrowserUI folder and run

webpack -w

Which will quickly update things each time you save a file. Similarly, you can use

gulp watch

to keep less and pug up to date if you're working in those kinds of files.

Building C# Source Code

To build the .net/C# part of Bloom, on Windows you'll need at least a 2015 Community edition of Visual Studio (for Linux, see Linux section below).

It will avoid some complications if you update to master branch now, before adding the dependencies that follow.

Before you'll be able to build you'll have to download some binary dependencies (see below).

On Linux you'll also have to make sure that you have installed some dependencies (see below).

To build Bloom you can open and build the solution in Visual Studio or MonoDevelop, or build from the command line using msbuild/xbuild.

Get Binary Dependencies

In the build directory, run



That will take several minutes the first time, and afterwards will be quick as it only downloads what has changed. When you change branches, run this again.

About Bloom Dependencies

Javascript dependencies should be introduced using

npm install <modulename> --save

Typescript definition files should be introduced using

tsd install <modulename> --save

Our Palaso libraries hold the classes that are common to multiple products.

Our **PdfDroplet **engine drives the booklet-making in the Publish tab. If you need to build PdfDroplet from source, see

Our Chorus library provides the Send/Receive functionality.

GeckoFX: Much of Bloom happens in its embedded Firefox browser. This has two parts: the XulRunner engine, and the GeckoFX .net wrapper. As of Bloom version 3.8, this comes in via a nuget package.

Bloom uses various web services that require identification. We can't really keep those a secret, but we can at least not make them google'able by not checking them into github. To get the file that contains user and test-level authorization codes, just get the connections.dll file out of a shipping version of a Bloom, and place it in your Bloom/DistFiles directory.

Disable analytics

We don't want developer and tester runs (and crashes) polluting our statistics. On Windows, add the environment variable "feedback" with value "off". On Linux, edit $HOME/.profile and add:

    export FEEDBACK=off

Special instructions for building on Linux

These notes were written by JohnT on 16 July 2014 based on previous two half-days working with Eberhard to get Bloom to build on a Precise Linux box. The computer was previously used to develop FLEx, so may have already had something that is needed. Sorry, I have not had the chance to try them on another system. If you do, please correct as needed.

Note that as of 16 July 2014, Bloom does not work very well on Linux. Something more may be needed by the time we get it fully working. Hopefully these notes will be updated.

Updated when Andrew was setting up his system on Precise Linux VM Oct. 2014. Note this VM also had previously been used for FLEx development.

At various points you will be asked for your password.

  1. Install wget

     sudo apt-get install wget
  2. Add the SIL keys for the main and testing SIL package repositories

     wget -O - | sudo apt-key add -
     wget -O - | sudo apt-key add -
  3. Make sure you have your system set up to look at the main and testing SIL repositories

    Install Synaptic if you haven't (sudo apt-get install synaptic).

    You need Synaptic to look in some extra places for components. In Synaptic, go to Settings->Repositories, Other Software tab. You want to see the following lines (replace precise with your distribution version): precise main precise-experimental main precise main precise-experimental main

    If some are missing, click add and paste the missing line, then insert 'deb' at the start, then confirm.

    (May help to check for and remove any lines that refer to the obsolete, if you've been doing earlier work on SIL stuff.)

  4. Update your system:

     sudo apt-get update
     sudo apt-get upgrade
  5. Clone the Bloom repository:

     mkdir $HOME/palaso
     cd $HOME/palaso
     git clone

    This should leave you in the default branch, which is currently correct for Linux. Don't be misled into activating the Linux branch, which is no longer used.

  6. Install MonoDevelop 5 (or later)

    A current MonoDevelop can be found on launchpad: or

    Follow the installation instructions on the launchpad website (currently a link called "Read about installing").

    Make a shortcut to launch MonoDevelop (or just use this command line). The shortcut should execute something like this:

     bash -c 'PATH=/opt/monodevelop/bin:$PATH; \
         export MONO_ENVIRON="$HOME/palaso/bloom-desktop/environ"; \
         export MONO_GAC_PREFIX=/opt/monodevelop:/opt/mono4-sil:/usr:/usr/local; \'

    Correct the path in MONO_ENVIRON to point to the Bloom source code directory.

  7. Install the dependencies needed for Bloom

     cd $HOME/palaso/bloom-desktop/build
     ./install-deps # (Note the initial dot)

    This will also install a custom mono version in /opt/mono4-sil. However, to successfully use it with MonoDevelop, you'll need to do some additional steps.

    Copy this script to /opt/mono4-sil/bin:

     sudo mv mono4-sil /opt/mono4-sil/bin
     sudo chmod +x /opt/mono4-sil/bin/mono-sil

    Delete /opt/mono4-sil/bin/mono and create two symlinks instead:

     sudo rm /opt/mono4-sil/bin/mono
     sudo ln -s /opt/mono4-sil/bin/mono-sgen /opt/mono4-sil/bin/mono-real
     sudo ln -s /opt/mono4-sil/bin/mono-sil /opt/mono4-sil/bin/mono
  8. Get binary dependencies:

     cd $HOME/palaso/bloom-desktop/build
     ./  # (Note the initial dot)
     cd ..
     . environ #(note the '.')
     sudo mozroots --import --sync
  9. Open solution in MonoDevelop

    Run MonoDevelop using the shortcut. Open the solution BloomLinux.sln. Go to Edit -> Preferences, Packages/Sources. The list should include, and (not sure the second is necessary).

    Add the /opt/mono4-sil/ as additional runtime in MonoDevelop (Edit -> Preferences, Projects/.NET Runtimes). Currently, this is (Oct. 2014).

    When you want to run Bloom you'll have to select the /opt/mono4-sil/ as current runtime (Project/Active Runtime).

    At this point you should be able to build the whole BloomLinux solution (right-click in Solution pane, choose Build).

  10. You'll have to remember to redo the symlink step (end of #7) every time you install a new mono4-sil package. You'll notice quickly if you forget because you get an error saying that it can't find XULRUNNER - that's an indication that it didn't source the environ file, either because the wrong runtime is selected or /opt/mono4-sil/bin/mono points to mono-sgen instead of the wrapper script mono4-sil.

Hopefully we can streamline this process eventually.

Registry settings

One responsibility of Bloom desktop is to handle url's starting with "bloom://"", such as those used in the bloom library web site when the user clicks "open in Bloom." Making this work requires some registry settings. These are automatically created when you run Bloom. If you have multiple versions installed, just make sure that the one you ran most recently is the one you want to do the download.


Please see Tips for Testing Palaso Software


Bloom is open source, using the MIT License. It is Copyright SIL International. "Bloom" is a registered trademark of SIL International.

You can’t perform that action at this time.