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.
|.net Unit tests||(part of above build)|
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 (https://yarnpkg.com/lang/en/docs/install/#windows-stable)
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 nvm-setup.zip 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- https://raw.githubusercontent.com/creationix/nvm/v0.33.8/install.sh | bash export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # 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
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 npm-build.sh 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
Which will quickly update things each time you save a file. Similarly, you can use
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
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
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 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.
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:
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.
sudo apt-get install wget
Add the SIL keys for the main and testing SIL package repositories
wget -O - http://linux.lsdev.sil.org/downloads/sil-testing.gpg | sudo apt-key add - wget -O - http://packages.sil.org/sil.gpg | sudo apt-key add -
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
Other Softwaretab. You want to see the following lines (replace
precisewith your distribution version):
http://packages.sil.org/ubuntu precise main http://packages.sil.org/ubuntu precise-experimental main http://linux.lsdev.sil.org/ubuntu precise main http://linux.lsdev.sil.org/ubuntu 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
ppa.palaso.org, if you've been doing earlier work on SIL stuff.)
Update your system:
sudo apt-get update sudo apt-get upgrade
Clone the Bloom repository:
mkdir $HOME/palaso cd $HOME/palaso git clone https://github.com/BloomBooks/BloomDesktop.git
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.
Install MonoDevelop 5 (or later)
A current MonoDevelop can be found on launchpad: https://launchpad.net/~ermshiperete/+archive/ubuntu/monodevelop or https://launchpad.net/~ermshiperete/+archive/ubuntu/monodevelop-beta.
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; \ monodevelop-launcher.sh'
Correct the path in MONO_ENVIRON to point to the Bloom source code directory.
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:
wget https://raw.githubusercontent.com/sillsdev/mono-calgary/develop/mono-sil 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
Get binary dependencies:
cd $HOME/palaso/bloom-desktop/build ./getDependencies-Linux.sh # (Note the initial dot) cd .. . environ #(note the '.') sudo mozroots --import --sync
Open solution in MonoDevelop
Run MonoDevelop using the shortcut. Open the solution BloomLinux.sln. Go to
Edit -> Preferences,
Packages/Sources. The list should include
http://build.palaso.org/guestAuth/app/nuget/v1/FeedService.svc/(not sure the second is necessary).
Add the /opt/mono4-sil/ as additional runtime in MonoDevelop (
Edit -> Preferences,
Projects/.NET Runtimes). Currently, this is 126.96.36.199 (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).
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.
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.