Building from Source
Relevant source files
The following files were used as context for generating this wiki page:
Building Matterbridge from source allows developers and advanced users to customize the binary, enable experimental features, and optimize the application for specific hardware constraints. While pre-compiled binaries are the standard distribution method, local compilation is necessary for features requiring specific licensing compliance, such as WhatsApp multidevice support.
The build process relies on the Go toolchain and supports cross-platform compilation. It can be performed natively or within isolated environments like Docker to ensure reproducibility across different operating systems.
Sources: README.md:201-206, vendor/golang.org/x/sys/unix/README.md:14-22
Prerequisites and Environment Setup
Before initiating a build, the environment must meet specific software and hardware requirements. Matterbridge requires Go version 1.18 or higher.
Hardware Requirements
Compiling the application with all bridges enabled is resource-intensive. A standard build requires approximately 3GB of RAM. For environments with limited memory, specific build tags can be used to reduce this requirement to approximately 0.5GB.
Sources: README.md:206-211
Build Configuration Variables
The following environment variables and settings influence the compilation output:
| Variable | Description | Usage |
|---|---|---|
CGO_ENABLED | Determines if the Go toolchain uses the C compiler (gcc). | Set to 0 for pure Go builds or on Windows. |
GOOS | Target operating system. | Used for cross-compilation (e.g., linux, windows, darwin). |
GOARCH | Target architecture. | Used for cross-compilation (e.g., amd64, arm64). |
Sources: README.md:213-214, vendor/golang.org/x/sys/unix/README.md:28-30
Compilation Procedures
The standard method for building Matterbridge utilizes the go install command. This fetches the source code and compiles it into the user's $GOPATH/bin directory.
Standard Build Commands
Users can choose between the latest stable release or the development master branch.
# Install latest stable release
go install github.com/42wim/matterbridge
# Install latest development version (master)
go install github.com/42wim/matterbridge@master
Sources: README.md:216-224
Build Flow Logic
The following diagram illustrates the decision process for selecting build parameters based on system resources and feature requirements.
This diagram shows the conditional path a developer takes to optimize the Matterbridge binary during compilation.
Sources: README.md:208-250
Conditional Feature Inclusion (Build Tags)
Matterbridge uses Go build tags to conditionally include or exclude specific bridges and libraries. This is primarily used for memory optimization or to handle third-party libraries with specific licenses.
Reducing Binary Footprint
The Microsoft Teams bridge is one of the most resource-heavy components. Excluding it significantly reduces the memory required for compilation.
# Build without MS Teams and Zulip
go install -tags nomsteams,nozulip github.com/42wim/matterbridge
Sources: README.md:226-228
WhatsApp Multidevice Support
The library used for WhatsApp multidevice support includes a GPL3 library. Due to licensing constraints (preventing the core Matterbridge from being forced into a GPL license), binaries for this feature are not provided. Users must compile this manually using the whatsappmulti tag.
# Build with WhatsApp multidevice support
go install -tags whatsappmulti github.com/42wim/matterbridge@master
Sources: README.md:237-248
Testing and Verification
After building from source, it is critical to verify the integrity of the binary through automated tests and quality checks.
Automated Testing
The standard Go testing tool is used to execute the test suite. It is recommended to run tests with the race detector enabled to identify concurrency issues.
# Run all tests with race detection
go test -race ./...
Sources: vendor/github.com/pelletier/go-toml/v2/CONTRIBUTING.md:78, vendor/github.com/minio/minio-go/v7/CONTRIBUTING.md:21
Code Coverage and Benchmarking
For contributors, verifying that new changes do not degrade performance or reduce test coverage is mandatory.
- Coverage: Use
go tool coverto ensure all lines of code touched by changes are tested. - Performance: Benchmarks are executed using
go test -bench=.. Results should be compared usingbenchstatto verify that no performance penalties are introduced.
Sources: vendor/github.com/pelletier/go-toml/v2/CONTRIBUTING.md:88-103
Summary
Building Matterbridge from source provides the flexibility to tailor the application to specific needs, such as enabling WhatsApp multidevice support or minimizing memory usage through build tags like nomsteams. By utilizing the standard Go toolchain and adhering to the recommended testing and verification practices, developers can ensure the resulting binary is stable and optimized for their specific environment.
Sources: README.md:208-211, README.md:237-240