Bloom 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. For more information, see https://bloomlibrary.org/about. For user documentation, see https://docs.bloomlibrary.org.
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 is growing up to be a pure React-driven offline-capable web app, with a C# backend. In its current state, Bloom is hybrid of C#/web app in which the bits of the UI are gradually moving to html.
- Install C# dependencies
./build/getDependencies-windows.sh-
Install volta globally on your computer. This will provide you with the correct node and yarn. You may need to restart your computer for the installation to take effect.
-
Install browser code dependencies:
cd src/content
yarn
cd ../BloomBrowserUI
yarn- In
/src/BloomBrowserUI, runyarn build.
Make sure you have the C# Devkit extensions installed. Run and Debug through the gui or F5.
- Open Bloom.sln in Visual Studio
- Build the "WebView2PdfMaker" project
- Run the "BloomExe" project
We don't want developer and tester runs (and crashes) polluting our statistics. On Windows, add the environment variable "feedback" with value "off".
In a terminal, run dotnet tool restore. This will install any tools we have put in .config/dotnet-tools.json along with the correct versions.
In Visual Studio, under Extensions, install "CSharpier". The extension's version will not be the same as the CSharpier installed by 'dotnet tool restore', but that's not a problem.
In Tools/Options, under CSharpier:General, set Reformat with CSharpier on Save to true. Note that you should set it for this solution, not globally.
You should also install the CSharpier extension in VSCode.
CSharpier should be using the version specified in .config/dotnet-tools.json.
When upgrading to a new version of CSharpier, to format everything, run dotnet csharpier format src/BloomExe src/BloomTests src/WebView2PdfMaker.
To hide reformatting-only commits from git blame, add the sha of the commit to .git-blame-ignore-revs.
For Typescript formatting, we use the Prettier extension in VSCode.
To rebuild on typescript, less, and md changes in BloomBrowserUI, use yarn watch.
To rebuild less and other "content" on changes, see the various scripts in src/content's package.json.
For fast hot-reloading, first do one yarn build, to get all the (so-far) static assets. Then run yarn dev. Currently only some parts of the Bloom UI benefit from this (the ones implemented using ReactControl, including ReactDialog). You may need to run yarn watch in another terminal.
It may be helpful before submitting a PR to turn off yarn dev and run yarn build, then do a quick smoke test of your work. Yarn build creates the transpiled files that will be used by Bloom in production.
For performance reasons, you probably want to exclude at least the following in the Windows Defender settings:
- node.exe (process)
- Bloom source code folder (e.g.
C:/dev/BloomDesktop)
These are now being run using Vitest in the BloomBrowserUI folder (where all our Typescript currently lives). You can run 'yarn test' in a terminal there, and it will automatically re-run affected tests on every Save. There is also a vitest extension you can install in VsCode, which supports a new panel showing all the tests and allowing them to be run and debugged; it also puts icons in the test files that support running and debugging tests. Breakpoints can be set in VSCode itself. It takes a few seconds for a debug session to start.
For now, all tests are being run using Node and JsDom. This approach has limitations; JsDom's emulation of the browser DOM is imperfect. In particular, you can't do much with a Canvas, and you can't get layout measurements. The file vitest.setup.ts contains various mocks to make jsdom work a little better. Eventually, we hope to be able to run a subset of tests using a real browser.
Hold down CTRL as you launch Bloom.
We use YouTrack Kanban boards. Errors (via email or api) also flow into YouTrack, and we do some support from there by @mentioning users.
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. bloom-player), that server automatically rebuilds and publishes Bloom Alpha. Public channels are released by pressing a button on the TeamCity page. This "publish" process builds Bloom, runs tests, makes an installer, uploads it to S3, and writes out a little bit of json which the Bloom download page uses to display version-specific information to the user.
5.4 is the last version for Linux until we get rid of WinForms.
See the Version5.4 branch and ReadMe if you need to update it.
See this page for how to run it.
UI localization happens on Crowdin.
One responsibility of Bloom desktop is to handle url's starting with "bloom://"", such as those used on bloomlibrary.org when the user clicks "Translate into your language!" 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.
Bloom is open source, using the MIT License. It is Copyright SIL Global. "Bloom" is a registered trademark of SIL Global.
