From cc5fcede44e01203cb2c32ae3ca34a765730e3fe Mon Sep 17 00:00:00 2001 From: Simone Basso Date: Wed, 3 Feb 2021 19:29:12 +0100 Subject: [PATCH] doc: merge the engine and the cli readmes (#215) Part of https://github.com/ooni/probe/issues/1335 --- CONTRIBUTING.md | 6 +- Readme.md | 121 ++++++++++++++++---------------------- internal/engine/README.md | 83 -------------------------- 3 files changed, 56 insertions(+), 154 deletions(-) delete mode 100644 internal/engine/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 64c4b79..d0f9597 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/Readme.md b/Readme.md index 011205e..dbb8934 100644 --- a/Readme.md +++ b/Readme.md @@ -1,72 +1,25 @@ # 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. ## 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 - - - - - Label - org.ooni.probe.daily-run - - KeepAlive - - RunAtLoad - - - ProgramArguments - - /PATH/TO/BINARY/ooniprobe - --log-handler=syslog - run - unattended - - - StartInterval - 86400 - - - -``` - -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; diff --git a/internal/engine/README.md b/internal/engine/README.md deleted file mode 100644 index 058f124..0000000 --- a/internal/engine/README.md +++ /dev/null @@ -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 -```