doc: merge the engine and the cli readmes (#215)
Part of https://github.com/ooni/probe/issues/1335
This commit is contained in:
Simone Basso
GitHub
parent
31cf7d2fdf
commit
cc5fcede44
|
|
@ -10,9 +10,11 @@ reviewer is satisfied, they will merge the pull request.
|
|||
Please, before opening a new issue, check whether the issue or feature request
|
||||
you want us to consider has not already been reported by someone else.
|
||||
|
||||
For new issues, please use: https://github.com/ooni/probe.
|
||||
For new issues, please use: [github.com/ooni/probe](
|
||||
https://github.com/ooni/probe/issues/new?labels=ooni/probe-cli&assignee=bassosimone).
|
||||
|
||||
Please, also check https://github.com/ooni/probe-engine for legacy issues. This is
|
||||
Please, also check [github.com/ooni/probe-engine](
|
||||
https://github.com/ooni/probe-engine) for legacy issues. This is
|
||||
the repository where the measurement engine previously was located.
|
||||
|
||||
## PR requirements
|
||||
|
|
|
|||
121
Readme.md
121
Readme.md
|
|
@ -1,72 +1,25 @@
|
|||
# OONI Probe CLI
|
||||
|
||||
[](https://github.com/ooni/probe-cli/actions?query=workflow%3Alinux-debian-packages) [](https://github.com/ooni/probe/labels/ooni%2Fprobe-cli)
|
||||
[](https://godoc.org/github.com/ooni/probe-cli) [](https://github.com/ooni/probe-cli/actions?query=workflow%3Ashorttests) [](https://github.com/ooni/probe-cli/actions?query=workflow%3Aalltests) [](https://coveralls.io/github/ooni/probe-cli?branch=master) [](https://goreportcard.com/report/github.com/ooni/probe-cli) [](https://github.com/ooni/probe-cli/actions?query=workflow%3Alinux-debian-packages) [](https://github.com/ooni/probe/labels/ooni%2Fprobe-cli)
|
||||
|
||||
The next generation OONI Probe Command Line Interface.
|
||||
|
||||
## User setup
|
||||
|
||||
1. Go [into the releases](https://github.com/ooni/probe-cli/releases) and download the
|
||||
release for your architecture and platform
|
||||
Please, follow the instructions at [ooni.org/install/cli](https://ooni.org/install/cli)
|
||||
to install `ooniprobe`. If we do not support your use case, please let us know.
|
||||
|
||||
2. Extract the tarball with `tar xvzf ooniprobe_*.tar.gz`
|
||||
|
||||
3. Copy the `ooniprobe` binary into a location in your `$PATH`, for example
|
||||
`/usr/local/bin/ooniprobe`
|
||||
|
||||
4. Run `ooniprobe run` to perform all the tests
|
||||
|
||||
Optional:
|
||||
|
||||
Add a crontab entry (on linux) to run `ooniprobe` daily at a random time:
|
||||
|
||||
```bash
|
||||
(crontab -l 2>/dev/null; echo "$(( ( RANDOM % 60 ) + 1 )) $(( ( RANDOM % 24 ) + 1 )) * * * ooniprobe run") | crontab -
|
||||
```
|
||||
|
||||
On macOS you can configure OONI Probe to run automatically using launchd.
|
||||
|
||||
Below is a sample launchd script, that should be placed inside of
|
||||
`~/Library/LaunchAgents/org.ooni.probe.cli.plist`.
|
||||
|
||||
Be sure to replace `/PATH/TO/BINARY/ooniprobe` with the actual install location of the
|
||||
`ooniprobe` binary.
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>org.ooni.probe.daily-run</string>
|
||||
|
||||
<key>KeepAlive</key>
|
||||
<false/>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/PATH/TO/BINARY/ooniprobe</string>
|
||||
<string>--log-handler=syslog</string>
|
||||
<string>run</string>
|
||||
<string>unattended</string>
|
||||
</array>
|
||||
|
||||
<key>StartInterval</key>
|
||||
<integer>86400</integer>
|
||||
|
||||
</dict>
|
||||
</plist>
|
||||
```
|
||||
|
||||
Once you have written the file, you can enable `ooniprobe` to run automatically by
|
||||
doing: `launchctl load org.ooni.probe.cli.plist`.
|
||||
Once `ooniprobe` is installed, try `ooniprobe help` to get interactive help.
|
||||
|
||||
## Reporting issues
|
||||
|
||||
Please, report issues with this codebase at https://github.com/ooni/probe. Please, make
|
||||
sure you tag such issues using the `ooni/probe-cli` label.
|
||||
Please, report issues with this codebase at [github.com/ooni/probe](
|
||||
https://github.com/ooni/probe/issues/new?labels=ooni/probe-cli&assignee=bassosimone).
|
||||
Please, make sure you tag such issues using the `ooni/probe-cli` label.
|
||||
|
||||
## Repository organization
|
||||
|
||||
Every top-level directory contains an explanatory README file.
|
||||
|
||||
## Development setup
|
||||
|
||||
|
|
@ -77,31 +30,61 @@ need Mingw-w64 installed). The most basic build command is:
|
|||
go build -v ./cmd/ooniprobe
|
||||
```
|
||||
|
||||
To compile a release used the `build.sh` script. For more information
|
||||
This will generate a binary called `ooniprobe` in the current directory.
|
||||
|
||||
```bash
|
||||
./build.sh help
|
||||
```
|
||||
## Update bundled assets
|
||||
|
||||
The output generated by this command should provide you with updated information
|
||||
regarding the pre-requisites for building (and cross-building) `ooniprobe` as well
|
||||
as useful information regarding cross compiling.
|
||||
|
||||
To update bundled binary data use:
|
||||
To update bundled assets use:
|
||||
|
||||
```bash
|
||||
./updatebindata.sh
|
||||
```
|
||||
|
||||
Then commit the changes.
|
||||
|
||||
## Android bindings
|
||||
|
||||
```bash
|
||||
./build-android.bash
|
||||
```
|
||||
|
||||
We automatically build Android bindings whenever commits are pushed to the
|
||||
`mobile-staging` branch. Such builds could be integrated by using:
|
||||
|
||||
```Groovy
|
||||
implementation "org.ooni:oonimkall:VERSION"
|
||||
```
|
||||
|
||||
Where VERSION is like `2020.03.30-231914` corresponding to the
|
||||
time when the build occurred.
|
||||
|
||||
## iOS bindings
|
||||
|
||||
```bash
|
||||
./build-ios.bash
|
||||
```
|
||||
|
||||
We automatically build iOS bindings whenever commits are pushed to the
|
||||
`mobile-staging` branch. Such builds could be integrated by using:
|
||||
|
||||
```ruby
|
||||
pod 'oonimkall', :podspec => 'https://dl.bintray.com/ooni/ios/oonimkall-VERSION.podspec'
|
||||
```
|
||||
|
||||
Where VERSION is like `2020.03.30-231914` corresponding to the
|
||||
time when the build occurred.
|
||||
|
||||
## Updating dependencies
|
||||
|
||||
`go get -u -v ./... && go mod tidy`
|
||||
```bash
|
||||
go get -u -v ./... && go mod tidy
|
||||
```
|
||||
|
||||
## Releasing
|
||||
|
||||
1. update binary data as described above;
|
||||
|
||||
2. update `internal/version/version.go`;
|
||||
2. update `version/version.go`;
|
||||
|
||||
3. make sure you have updated dependencies;
|
||||
|
||||
|
|
|
|||
|
|
@ -1,83 +0,0 @@
|
|||
# OONI probe measurement engine
|
||||
|
||||
[](https://godoc.org/github.com/ooni/probe-engine) [](https://github.com/ooni/probe-engine/actions?query=workflow%3Ashorttests) [](https://github.com/ooni/probe-engine/actions?query=workflow%3Aalltests) [](https://coveralls.io/github/ooni/probe-engine?branch=master) [](https://goreportcard.com/report/github.com/ooni/probe-engine)
|
||||
|
||||
This repository contains OONI probe's [measurement engine](
|
||||
https://github.com/ooni/spec/tree/master/probe#engine). That is, the
|
||||
piece of software that implements OONI nettests as well as all the
|
||||
required functionality to run such nettests.
|
||||
|
||||
We expect you to use the Go version indicated in [go.mod](go.mod).
|
||||
|
||||
## Integrating ooni/probe-engine
|
||||
|
||||
We recommend pinning to a specific version of probe-engine:
|
||||
|
||||
```bash
|
||||
go get -v github.com/ooni/probe-engine@VERSION
|
||||
```
|
||||
|
||||
See also the [workflows/using.yml](.github/workflows/using.yml) test
|
||||
where we check that the latest commit can be imported by a third party.
|
||||
|
||||
We do not provide any API stability guarantee.
|
||||
|
||||
## Building miniooni
|
||||
|
||||
[miniooni](cmd/miniooni) is a small command line client used for
|
||||
research and quality assurance testing. Build using:
|
||||
|
||||
```bash
|
||||
go build -v ./cmd/miniooni/
|
||||
```
|
||||
|
||||
See also `./build-cli.bash` for more advanced builds (e.g. to create
|
||||
statically linked and/or stripped binaries).
|
||||
|
||||
We don't provide any `miniooni` command line flags stability guarantee.
|
||||
|
||||
See
|
||||
|
||||
```bash
|
||||
./miniooni --help
|
||||
```
|
||||
|
||||
for more help.
|
||||
|
||||
## Building Android bindings
|
||||
|
||||
```bash
|
||||
./build-android.bash
|
||||
```
|
||||
|
||||
We automatically build Android bindings whenever commits are pushed to the
|
||||
`mobile-staging` branch. Such builds could be integrated by using:
|
||||
|
||||
```Groovy
|
||||
implementation "org.ooni:oonimkall:VERSION"
|
||||
```
|
||||
|
||||
Where VERSION is like `2020.03.30-231914` corresponding to the
|
||||
time when the build occurred.
|
||||
|
||||
## Building iOS bindings
|
||||
|
||||
```bash
|
||||
./build-ios.bash
|
||||
```
|
||||
|
||||
We automatically build iOS bindings whenever commits are pushed to the
|
||||
`mobile-staging` branch. Such builds could be integrated by using:
|
||||
|
||||
```ruby
|
||||
pod 'oonimkall', :podspec => 'https://dl.bintray.com/ooni/ios/oonimkall-VERSION.podspec'
|
||||
```
|
||||
|
||||
Where VERSION is like `2020.03.30-231914` corresponding to the
|
||||
time when the build occurred.
|
||||
|
||||
## Updating dependencies
|
||||
|
||||
```
|
||||
go get -u -v ./... && go mod tidy
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user