c/ooni-probe-cli
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: merge the engine and the cli readmes (#215)

Browse Source 
Part of https://github.com/ooni/probe/issues/1335
This commit is contained in:
Simone Basso 2021-02-03 19:29:12 +01:00 committed by GitHub
parent 31cf7d2fdf
commit cc5fcede44
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 56 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
CONTRIBUTING.md
View File

@ -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 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. 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. the repository where the measurement engine previously was located.
## PR requirements ## PR requirements

121
Readme.md
View File

@ -1,72 +1,25 @@
# OONI Probe CLI # OONI Probe CLI
[![linux-debian-packages](https://github.com/ooni/probe-cli/workflows/linux-debian-packages/badge.svg)](https://github.com/ooni/probe-cli/actions?query=workflow%3Alinux-debian-packages) [![GitHub issues by-label](https://img.shields.io/github/issues/ooni/probe/ooni/probe-cli?style=plastic)](https://github.com/ooni/probe/labels/ooni%2Fprobe-cli) [![GoDoc](https://godoc.org/github.com/ooni/probe-cli?status.svg)](https://godoc.org/github.com/ooni/probe-cli) [![Short Tests Status](https://github.com/ooni/probe-cli/workflows/shorttests/badge.svg)](https://github.com/ooni/probe-cli/actions?query=workflow%3Ashorttests) [![All Tests Status](https://github.com/ooni/probe-cli/workflows/alltests/badge.svg)](https://github.com/ooni/probe-cli/actions?query=workflow%3Aalltests) [![Coverage Status](https://coveralls.io/repos/github/ooni/probe-cli/badge.svg?branch=master)](https://coveralls.io/github/ooni/probe-cli?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/ooni/probe-cli)](https://goreportcard.com/report/github.com/ooni/probe-cli) [![linux-debian-packages](https://github.com/ooni/probe-cli/workflows/linux-debian-packages/badge.svg)](https://github.com/ooni/probe-cli/actions?query=workflow%3Alinux-debian-packages) [![GitHub issues by-label](https://img.shields.io/github/issues/ooni/probe/ooni/probe-cli?style=plastic)](https://github.com/ooni/probe/labels/ooni%2Fprobe-cli)
The next generation OONI Probe Command Line Interface. The next generation OONI Probe Command Line Interface.
## User setup ## User setup
1. Go [into the releases](https://github.com/ooni/probe-cli/releases) and download the Please, follow the instructions at [ooni.org/install/cli](https://ooni.org/install/cli)
release for your architecture and platform 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` Once `ooniprobe` is installed, try `ooniprobe help` to get interactive help.
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`.
## Reporting issues ## Reporting issues
Please, report issues with this codebase at https://github.com/ooni/probe. Please, make Please, report issues with this codebase at [github.com/ooni/probe](
sure you tag such issues using the `ooni/probe-cli` label. 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 ## Development setup
@ -77,31 +30,61 @@ need Mingw-w64 installed). The most basic build command is:
go build -v ./cmd/ooniprobe 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 ## Update bundled assets
./build.sh help
```
The output generated by this command should provide you with updated information To update bundled assets use:
regarding the pre-requisites for building (and cross-building) `ooniprobe` as well
as useful information regarding cross compiling.
To update bundled binary data use:
```bash ```bash
./updatebindata.sh ./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 ## Updating dependencies
`go get -u -v ./... && go mod tidy` ```bash
go get -u -v ./... && go mod tidy
```
## Releasing ## Releasing
1. update binary data as described above; 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; 3. make sure you have updated dependencies;

83
internal/engine/README.md
View File

@ -1,83 +0,0 @@
# OONI probe measurement engine
[![GoDoc](https://godoc.org/github.com/ooni/probe-engine?status.svg)](https://godoc.org/github.com/ooni/probe-engine) [![Short Tests Status](https://github.com/ooni/probe-engine/workflows/shorttests/badge.svg)](https://github.com/ooni/probe-engine/actions?query=workflow%3Ashorttests) [![All Tests Status](https://github.com/ooni/probe-engine/workflows/alltests/badge.svg)](https://github.com/ooni/probe-engine/actions?query=workflow%3Aalltests) [![Coverage Status](https://coveralls.io/repos/github/ooni/probe-engine/badge.svg?branch=master)](https://coveralls.io/github/ooni/probe-engine?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/ooni/probe-engine)](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
```