Awesome
<!-- Adapted from https://github.com/othneildrew/Best-README-Template, which is under the MIT license. So, this file is also under the MIT license. --> <div align="center">OONI Probe Measurement Engine and CLI
User guide · API docs · Report bug · Request feature · Tutorials
</div> <details> <summary>Table of Contents</summary> <ol> <li><a href="#about-this-project">About this project</a></li> <li><a href="#install-instructions">Install instructions</a></li> <li><a href="#nightly-builds">Nightly Builds</a></li> <li><a href="#build-instructions">Build instructions<a></li> <li><a href="#contributing">Contributing</a></li> <li><a href="#license">License</a></li> <li><a href="#updating-dependencies">Updating dependencies</a></li> <li><a href="#releasing">Releasing<a></li> <li><a href="#semantic-versioning-policy">Semantic versioning policy<a></li> </ol> </details> <hr>About this project
The Open Observatory of Network Interference (OONI) is a non-profit free software project that aims to empower decentralized efforts in documenting Internet censorship around the world.
This repository contains the following Go packages:
-
the ooniprobe command line client (cmd/ooniprobe);
-
the test helper server (internal/cmd/oohelperd);
-
the mobile library (pkg/oonimkall);
-
the measurement-engine library (internal);
-
the miniooni experimental command line client (internal/cmd/miniooni).
Every top-level directory in this repository contains an explanatory README file.
Install instructions
Follow the instructions at ooni.org/install/cli
to install ooniprobe
precompiled binaries for Windows, macOS, and
Debian/Ubuntu. Once ooniprobe
is installed, refer to the
user guide.
Nightly builds
We publish nightly builds using the rolling release tag. These
builds use the latest commit of the master
branch.
Developer instructions
To setup development for this repository you need Go >= 1.15. The
./script/go.bash
script will automatically download the expected
version of Go mentioned in the GOVERSION file (i.e.,
go1.21.11) and use it for building.
You can also bypass ./script/go.bash
and build ooniprobe manually using
go build ...
but, in such a case, note that:
-
using an older version that the one mentioned in GOVERSION is definitely not recommended and may not even compile;
-
using later versions should work as intended for core functionality but extra functionality may be disabled or not working as intended.
Here's why: we rely on packages forked from the standard library; so, it is more robust to use the same version of Go from which we forked those packages from.
You will also need a C compiler. On Linux and other Unix systems both GCC and Clang will work. If you're using Windows, we recommend installing Ubuntu or Debian on the Windows Subsystem for Linux. If you're targeting Windows, you should also install the mingw-w64 cross-compiler.
Debian developer setup
The following commands show how to setup a development environment using Debian 12 ("bookworm"). The same instructions should also work for Ubuntu 22.04 LTS.
# install the compilers, git, and the root CA
sudo apt install golang build-essential ca-certificates git
# [optional] install mingw-w64 if you're targeting windows
sudo apt install mingw-w64
Fedora developer setup
The following commands show how to setup a development environment using Fedora, as long as your Fedora uses Go >= 1.15.
# install the compilers and git
sudo dnf install golang make gcc gcc-c++ git
# [optional] install mingw-w64 if you're targeting windows
sudo dnf install mingw64-gcc mingw64-gcc-c++
macOS developer setup
The following commands show how to setup a development environment using macOS. We assume you have already installed Homebrew, which should also install the Xcode command line tools.
Then, you need to follow these instructions:
# install the compiler
brew install go
The ./script/go.bash
script
The ./script/go.bash
script requires Go >= 1.15 and automates installing and
using the correct version of Go. Running this script as follows:
./script/go.bash build -v -ldflags '-s -w' ./internal/cmd/miniooni
Is equivalent to running these commands:
go install -v golang.org/dl/go1.21.11@latest
$HOME/go/bin/go1.21.11 download
export GOTOOLCHAIN=local
$HOME/sdk/go1.21.11/bin/go build -v -ldflags '-s -w' ./internal/cmd/miniooni
Common build targets
This section shows how to build using ./script/go.bash
. If you want to bypass
using this script, just run go
instead of ./script/go.bash
.
You can compile ooniprobe
using:
./script/go.bash build -v -ldflags '-s -w' ./cmd/ooniprobe
This command will generate a stripped binary called ooniprobe
in the toplevel directory.
Likewise, you can compile miniooni
using:
./script/go.bash build -v -ldflags '-s -w' ./internal/cmd/miniooni
This command will generate a stripped binary called miniooni
in the toplevel directory.
And oohelperd
using:
./script/go.bash build -v -ldflags '-s -w' ./internal/cmd/oohelperd
This command will generate a stripped binary called oohelperd
in the toplevel directory.
Contributing
Please, see CONTRIBUTING.md.
License
SPDX-License-Identifier: GPL-3.0-or-later
Releasing
We build releases using Makefile, which requires GNU make. Run
make help
for detailed usage.
See also the relevant section of CONTRIBUTING.md.
Semantic versioning policy
The mobile library is a public package for technical reasons. Go mobile tools require
a public package to build from. Yet, we don't consider API breakages happening in
such a package to be sufficient to bump our major version number. For us, the mobile
library is just a mean to implement OONI Probe Android and OONI Probe iOS. We'll
only bump the major version number if we change ./cmd/ooniprobe
's CLI.