112 lines
5.2 KiB
Markdown
112 lines
5.2 KiB
Markdown
## Bloom
|
|
|
|
Bloom can be downloaded at https://bloom.oscillate.io/download.
|
|
|
|
Bloom is a debug interface for embedded systems development on GNU/Linux. This is the official repository for Bloom's
|
|
source code. For information on how to use Bloom, please visit https://bloom.oscillate.io.
|
|
|
|
### License
|
|
Bloom is released under the LGPLv3 license. See LICENSE.md
|
|
|
|
---
|
|
|
|
### Building Bloom from source
|
|
|
|
> Bloom is typically distributed via binary packages, which can be downloaded via the
|
|
> [downloads page](https://bloom.oscillate.io/download). These packages contain a prebuilt binary of Bloom, as well as
|
|
> some of its dependencies (dynamically linked libraries). These dependencies are distributed with Bloom because they
|
|
> work well with it. This is known because countless hours have been spent, testing them, on many Linux distros. If you
|
|
> choose to use a binary package, you can be fairly confident that you won't run into any compatability issues.
|
|
>
|
|
> However, if you choose to build Bloom from source, it will use your system's shared libraries, which may be of a
|
|
> different version to the one that was tested against. You will be more likely to face compatability issues.
|
|
>
|
|
> In an ideal world, using a shared library with a different minor version won't break anything, but this is not always
|
|
> the reality.
|
|
|
|
#### Dependencies
|
|
|
|
To compile Bloom, the following dependencies must be resolved:
|
|
|
|
The accompanying package names are from the Debian (APT) package repositories - package names will vary across package
|
|
repositories.
|
|
|
|
- CMake version 3.22 or later
|
|
- G++10 or later
|
|
- libusb v1.0 (`libusb-1.0-0-dev`)
|
|
- libhidapi (0.11.2 or later) (`libhidapi-dev`)
|
|
- yaml-cpp (version 0.7.0 or later) (`libyaml-cpp-dev`)
|
|
- libprocps (`libprocps-dev`)
|
|
- PHP CLI version 8.2 or later, with the xml and multibyte string extensions (`php8.2-cli`, `php8.2-xml`,
|
|
`php8.2-mbstring`)
|
|
- Qt Version 6.2.4 or later (see note below)
|
|
|
|
When installing Qt, it's best to install via the Qt installer: https://www.qt.io/download
|
|
|
|
You may also need to install mesa-common-dev and libglu1-mesa-dev (Qt dependencies):
|
|
|
|
If you already have another version of Qt installed, you may need to temporarily point qtchooser to the right place
|
|
(unless you can figure out another way to make cmake use the right Qt binaries (specifically, the moc)):
|
|
```
|
|
# Set the appropriate paths to your Qt installation in here. You may want to backup this file incase you wish to revert the changes
|
|
# You may need to change the path below
|
|
sudo nano /usr/lib/x86_64-linux-gnu/qt-default/qtchooser/default.conf
|
|
```
|
|
|
|
#### Example build
|
|
|
|
```shell
|
|
# Build Bloom in [SOME_BUILD_DIR]
|
|
mkdir [SOME_BUILD_DIR];
|
|
cd [SOME_BUILD_DIR];
|
|
|
|
cmake [PATH_TO_BLOOM_SOURCE] -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=[PATH_TO_QT_INSTALLATION]/gcc_64/;
|
|
cmake --build ./;
|
|
|
|
# Install Bloom to /opt/bloom
|
|
sudo cmake --install ./;
|
|
|
|
# OR, install Bloom to [SOME_OTHER_INSTALLATION_DIR]
|
|
sudo cmake --install ./ --prefix [SOME_OTHER_INSTALLATION_DIR];
|
|
```
|
|
#### Other notes on building from source:
|
|
|
|
- To specify the compiler path, use `-DCMAKE_CXX_COMPILER=...`:
|
|
```
|
|
cmake [PATH_TO_BLOOM_SOURCE] -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=[PATH_TO_QT_INSTALLATION]/gcc_64/ -DCMAKE_CXX_COMPILER=/usr/bin/g++-10;
|
|
```
|
|
- We do **not** modify the RUNPATH of release builds. This means that running your release build, directly, may fail,
|
|
due to missing Qt shared libraries. We create an invocation script (`[INSTALL_DIR]/bin/bloom.sh`) upon installation,
|
|
which will set the `LD_LIBRARY_PATH` environment variable. You'll need to use that script to run a release build
|
|
(unless all of your shared libraries can be found in the typical locations).
|
|
- For debug builds, we **do** modify the RUNPATH (as it's easier for me, during development), but you should note that
|
|
this is currently hardcoded to point to my Qt installation. See the root CMakeLists.txt for more.
|
|
- Once you've installed Bloom, you'll need to create a symlink to Bloom's invocation script, in `/usr/bin/`, to run
|
|
`bloom` without having to supply the full path: `sudo ln -s /opt/bloom/bin/bloom.sh /usr/bin/bloom;`
|
|
- If you're installing on Ubuntu 20.04 or older, you may need to move the installed udev rules, as they're expected
|
|
to reside in `/lib/udev/rules.d` on those systems. Move them via: `sudo mv /usr/lib/udev/rules.d/99-bloom.rules /lib/udev/rules.d/;`
|
|
|
|
### Excluding Insight at build time
|
|
|
|
The Insight component can be excluded at build time, via the `EXCLUDE_INSIGHT` flag.
|
|
You'll still need to satisfy the Qt dependency on the build machine, as other parts of Bloom use Qt, but you'll no
|
|
longer need to install GUI dependencies on every machine you intend to run Bloom on. Just build it once and distribute
|
|
the binary, along with the necessary shared objects.
|
|
|
|
To identify the necessary shared objects, copy the binary to one of those machines and run `ldd [PATH_TO_BLOOM_BINARY]`.
|
|
That will output a list of all the dependencies that `ld` couldn't satisfy - those will be what you need to distribute
|
|
(or manually install on each machine).
|
|
|
|
#### Example build excluding Insight
|
|
|
|
```shell
|
|
# Build Bloom in [SOME_BUILD_DIR]
|
|
mkdir [SOME_BUILD_DIR];
|
|
cd [SOME_BUILD_DIR];
|
|
|
|
cmake [PATH_TO_BLOOM_SOURCE] -DEXCLUDE_INSIGHT=1 -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=[PATH_TO_QT_INSTALLATION]/gcc_64/;
|
|
cmake --build ./;
|
|
|
|
...
|
|
```
|