all: imp docs, other improvements

HACKING.md

@@ -1,4 +1,4 @@
- #  *AdGuardHome* Developer Guidelines
+ #  AdGuard Home Developer Guidelines
 
 As of **December 2020**, this document is partially a work-in-progress, but
 should still be followed.  Some of the rules aren't enforced as thoroughly or

Makefile

@@ -1,4 +1,5 @@
-# Keep the Makefile POSIX-compliant.
+# Keep the Makefile POSIX-compliant.  We currently allow hyphens in
+# target names, but that may change in the future.
 #
 # See https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html.
 .POSIX:
@@ -11,7 +12,7 @@ GO = go
 # TODO(a.garipov): Add more default proxies using pipes after update to
 # Go 1.15.
 #
-# GOPROXY = https://goproxy.io|https://goproxy.cn
+# GOPROXY = https://goproxy.io|https://goproxy.cn|direct
 GOPROXY = https://goproxy.cn,https://goproxy.io,direct
 GPG_KEY_PASSPHRASE = not-a-real-password
 NPM = npm
@@ -34,8 +35,11 @@ ENV = env\
 
 # Keep the line above blank.
 
-# Keep this target first, so that a naked make would trigger a build.
-build: js-build go-gen go-build
+# Keep this target first, so that a naked make invocation triggers
+# a full build.
+build: deps quick-build
+
+quick-build: js-build go-build
 
 ci: deps test
 
@@ -45,25 +49,24 @@ test: js-test go-test
 
 # Here and below, keep $(SHELL) in quotes, because on Windows this will
 # expand to something like "C:/Program Files/Git/usr/bin/sh.exe".
-build-docker: ; $(ENV) "$(SHELL)" ./scripts/build-docker.sh
+build-docker: ; $(ENV) "$(SHELL)" ./scripts/make/build-docker.sh
 
-build-release: deps js-build go-gen
-	$(ENV) "$(SHELL)" ./scripts/build-release.sh
+build-release: deps js-build
+	$(ENV) "$(SHELL)" ./scripts/make/build-release.sh
 
-clean: ; $(ENV) "$(SHELL)" ./scripts/clean.sh
+clean: ; $(ENV) "$(SHELL)" ./scripts/make/clean.sh
 init:  ; git config core.hooksPath ./scripts/hooks
 
 js-build: ; $(NPM) $(NPM_FLAGS) run build-prod
 js-deps:  ; $(NPM) $(NPM_FLAGS) ci
 js-lint:  ; $(NPM) $(NPM_FLAGS) run lint
 js-test:  ; $(NPM) $(NPM_FLAGS) run test
 
-go-build: ; $(ENV) "$(SHELL)" ./scripts/go-build.sh
-go-deps:  ; $(ENV) "$(SHELL)" ./scripts/go-deps.sh
-go-gen:   ; $(ENV) $(GO) generate ./...
-go-lint:  ; $(ENV) "$(SHELL)" ./scripts/go-lint.sh
-go-test:  ; $(ENV) "$(SHELL)" ./scripts/go-test.sh
-go-tools: ; $(ENV) "$(SHELL)" ./scripts/go-tools.sh
+go-build: ; $(ENV) "$(SHELL)" ./scripts/make/go-build.sh
+go-deps:  ; $(ENV) "$(SHELL)" ./scripts/make/go-deps.sh
+go-lint:  ; $(ENV) "$(SHELL)" ./scripts/make/go-lint.sh
+go-test:  ; $(ENV) "$(SHELL)" ./scripts/make/go-test.sh
+go-tools: ; $(ENV) "$(SHELL)" ./scripts/make/go-tools.sh
 
 # TODO(a.garipov): Remove the legacy targets once the build
 # infrastructure stops using them.

README.md

@@ -58,7 +58,7 @@ It operates as a DNS server that re-routes tracking domains to a "black hole," t
     * [Reporting issues](#reporting-issues)
     * [Help with translations](#translate)
     * [Other](#help-other)
-* [Projects that use AdGuardHome](#uses)
+* [Projects that use AdGuard Home](#uses)
 * [Acknowledgments](#acknowledgments)
 * [Privacy](#privacy)
 
@@ -180,7 +180,7 @@ Open Terminal and execute these commands:
 ```bash
 git clone https://github.com/AdguardTeam/AdGuardHome
 cd AdGuardHome
-make deps build
+make
 ```
 
 Check the [`Makefile`](https://github.com/AdguardTeam/AdGuardHome/blob/master/Makefile) to learn about other commands.
@@ -190,11 +190,11 @@ In order to do this, specify `GOOS` and `GOARCH` env variables before running ma
 
 For example:
 ```
-env GOOS='linux' GOARCH='arm64' make build
+env GOOS='linux' GOARCH='arm64' make
 ```
 Or:
 ```
-make GOOS='linux' GOARCH='arm64' build
+make GOOS='linux' GOARCH='arm64'
 ```
 
 #### Preparing release
@@ -299,7 +299,7 @@ Here's what you can also do to contribute:
 4. Actualize the list of vetted *blocklists*. It it can be found in [client/src/helpers/filters/filters.json](https://github.com/AdguardTeam/AdGuardHome/blob/master/client/src/helpers/filters/filters.json).
 
 <a id="uses"></a>
-## Projects that use AdGuardHome
+## Projects that use AdGuard Home
 
 * Python library (https://github.com/frenck/python-adguardhome)
 * Hass.io add-on (https://github.com/hassio-addons/addon-adguard-home)
@@ -325,7 +325,7 @@ This software wouldn't have been possible without:
    * And many more node.js packages.
  * [whotracks.me data](https://github.com/cliqz-oss/whotracks.me)
 
-You might have seen that [CoreDNS](https://coredns.io) was mentioned here before — we've stopped using it in AdGuardHome. While we still use it on our servers for [AdGuard DNS](https://adguard.com/adguard-dns/overview.html) service, it seemed like an overkill for Home as it impeded with Home features that we plan to implement.
+You might have seen that [CoreDNS](https://coredns.io) was mentioned here before — we've stopped using it in AdGuard Home. While we still use it on our servers for [AdGuard DNS](https://adguard.com/adguard-dns/overview.html) service, it seemed like an overkill for Home as it impeded with Home features that we plan to implement.
 
 For a full list of all node.js packages in use, please take a look at [client/package.json](https://github.com/AdguardTeam/AdGuardHome/blob/master/client/package.json) file.
 

scripts/README.md

@@ -0,0 +1,141 @@
+ #  AdGuard Home Scripts
+
+##  `hooks/`: Git Hooks
+
+ ###  Usage
+
+Run `make init` from the project root.
+
+##  `querylog/`: Query Log Helpers
+
+ ###  Usage
+
+ *  `npm install`: install dependencies.  Run this first.
+ *  `npm run anonymize <source> <dst>`: read the query log from the `<source>`
+    and write anonymized version to `<dst>`.
+
+##  `make/`: Makefile Scripts
+
+The release channels are: `development` (the default), `edge`, `beta`, and
+`release`.  If verbosity levels aren't documented here, there are only two: `0`,
+don't print anything, and `1`, be verbose.
+
+ ###  `build-docker.sh`: Build A Multi-Architecture Docker Image
+
+**TODO(a.garipov):** Document this after we're done with the Docker stuff.
+
+ ###  `build-release.sh`: Build A Release For All Platforms
+
+Required environment:
+ *  `CHANNEL`: release channel, see above.
+ *  `GPG_KEY` and `GPG_KEY_PASSPHRASE`: data for `gpg`.  Only required if `SIGN`
+    is `1`.
+
+Optional environment:
+ *  `DIST_DIR`: the directory to build a release into.  The default value is
+    `dist`.
+ *  `GO`: set an alternarive name for the Go compiler.
+ *  `SIGN`: `0` to not sign the resulting packages, `1` to sign.  The default
+    value is `1`.
+ *  `VERBOSE`: `1` to be verbose.  This script calls `go-build.sh` with the
+    verbosity level one level lower, so to get verbosity level `2` in
+    `go-build.sh`, set this to `3` when calling `build-release.sh`.
+ *  `VERSION`: release version.  Will be set by `version.sh` if it is unset or
+    it has the default `Makefile` value of `v0.0.0`.
+
+ ###  `clean.sh`: Cleanup
+
+Optional environment:
+ *  `GO`: set an alternarive name for the Go compiler.
+
+Required environment:
+ *  `DIST_DIR`: the directory where a release has previously been built.
+
+ ###  `go-build.sh`: Build The Backend
+
+Optional environment:
+ *  `GOARM`: ARM processor options for the Go compiler.
+ *  `GOMIPS`: ARM processor options for the Go compiler.
+ *  `GO`: set an alternarive name for the Go compiler.
+ *  `OUT`: output binary name.
+ *  `PARALLELISM`: set the maximum number of concurrently run build commands
+    (that is, compiler, linker, etc.).
+ *  `VERBOSE`: verbosity level.  `1` shows every command that is run and every
+    Go package that is processed.  `2` also shows subcommands.  The default
+    value is `0`, don't be verbose.
+
+Required environment:
+ *  `CHANNEL`: release channel, see above.
+ *  `VERSION`: release version.
+
+ ###  `go-deps.sh`: Install Backend Dependencies
+
+Optional environment:
+ *  `GO`: set an alternarive name for the Go compiler.
+
+ ###  `go-lint.sh`: Run Backend Static Analyzers
+
+Don't forget to run `make go-tools` once first!
+
+Optional environment:
+ *  `EXIT_ON_ERROR`: if set to `0`, don't exit the script after the first
+    encountered error.  The default value is `1`.
+ *  `GO`: set an alternarive name for the Go compiler.
+ *  `VERBOSE`: verbosity level.  `1` shows every command that is run.  `2` also
+    shows subcommands.  The default value is `0`, don't be verbose.
+
+ ###  `go-test.sh`: Run Backend Tests
+
+Optional environment:
+ *  `GO`: set an alternarive name for the Go compiler.
+ *  `RACE`: set to `0` to not use the Go race detector.  The default value is
+    `1`, use the race detector.
+ *  `VERBOSE`: verbosity level.  `1` shows every command that is run and every
+    Go package that is processed.  `2` also shows subcommands.  The default
+    value is `0`, don't be verbose.
+
+ ###  `go-tools.sh`: Install Backend Tooling
+
+Installs the Go static analysis and other tools into `${PWD}/bin`.  Either add
+`${PWD}/bin` to your `$PATH` before all other entries, or use the commands
+directly, or use the commands through `make` (for example, `make go-lint`).
+
+Optional environment:
+ *  `GO`: set an alternarive name for the Go compiler.
+
+ ###  `version.sh`: Print The Current Version
+
+Required environment:
+ *  `CHANNEL`: release channel, see above.
+
+##  `snap/`: Snap GUI Files
+
+App icons (see https://github.com/AdguardTeam/AdGuardHome/pull/1836), Snap
+manifest file templates, and helper scripts.
+
+##  `translations/`: Twosky Integration Script
+
+ ###  Usage
+
+ *  `npm install`: install dependencies.  Run this first.
+ *  `npm run locales:download`: download and save all translations.
+ *  `npm run locales:upload`: upload the base `en` locale.
+ *  `npm run locales:summary`: show the current locales summary.
+ *  `npm run locales:unused`: show the list of unused strings.
+
+After the download you'll find the output locales in the `client/src/__locales/`
+directory.
+
+##  `whotracksme/`: Whotracks.me Database Converter
+
+A simple script that converts the Ghostery/Cliqz trackers database to a json format.
+
+ ###  Usage
+
+```sh
+yarn install
+node index.js
+```
+
+You'll find the output in the `whotracksmedb.json` file.  Then, move it to
+`client/src/helpers/trackers`.

scripts/install.sh

@@ -1,6 +1,6 @@
 #!/bin/sh
 
-# AdGuardHome installation script
+# AdGuard Home Installation Script
 #
 # 1. Download the package
 # 2. Unpack it
@@ -227,4 +227,4 @@ main() {
     log_info "  sudo ${AGH_DIR}/AdGuardHome -s start|stop|restart|status|install|uninstall"
 }
 
-main "$@"
+main "$@"

scripts/build-release.sh → scripts/make/build-release.sh

@@ -1,16 +1,19 @@
 #!/bin/sh
 
-# AdGuardHome release build script.
+# AdGuard Home Release Script
 #
 # The commentary in this file is written with the assumption that the
 # reader only has superficial knowledge of the POSIX shell language and
 # alike.  Experienced readers may find it overly verbose.
 
 # The default verbosity level is 0.  Show every command that is run if
-# the caller requested verbosity level greater than 1.  Otherwise, do
+# the caller requested verbosity level greater than 0.  Otherwise, do
 # nothing.
+#
+# The level of verbosity for the build script is the same minus one
+# level.  See below in build().
 readonly verbose="${VERBOSE:-0}"
-if [ "$verbose" -gt '1' ]
+if [ "$verbose" -gt '0' ]
 then
 	set -x
 fi
@@ -32,17 +35,17 @@ log() {
 	fi
 }
 
-log 'starting to build AdGuardHome release'
+log 'starting to build AdGuard Home release'
 
 # Require the channel to be set.  Additional validation is performed
 # later by go-build.sh.
 readonly channel="$CHANNEL"
 
 # Check VERSION against the default value from the Makefile.  If it is
 # that, use the version calculation script.
-if [ "${VERSION:-}" = 'v0.0.0' ]
+if [ "${VERSION:-}" = 'v0.0.0' -o "${VERSION:-}" = '' ]
 then
-	readonly version="$(sh ./scripts/version.sh)"
+	readonly version="$(sh ./scripts/make/version.sh)"
 else
 	readonly version="$VERSION"
 fi
@@ -59,7 +62,7 @@ then
 fi
 
 # The default distribution files directory is dist.
-readonly dist="${DIST:-dist}"
+readonly dist="${DIST_DIR:-dist}"
 
 # Give users the ability to override the go command from environment.
 # For example, to build two releases with two different Go versions and

scripts/go-build.sh → scripts/make/go-build.sh

@@ -1,26 +1,29 @@
 #!/bin/sh
 
-# AdGuardHome build script.
+# AdGuard Home Build Script
 #
 # The commentary in this file is written with the assumption that the
 # reader only has superficial knowledge of the POSIX shell language and
 # alike.  Experienced readers may find it overly verbose.
 
-# The default verbosity level is 0.  Show every command that is run if
-# the caller requested verbosity level greater than 1.  Also show
-# subcommands if the requested verbosity level is greater than 2.
-# Otherwise, do nothing.
+# The default verbosity level is 0.  Show every command that is run and
+# every package that is processed if the caller requested verbosity
+# level greater than 0.  Also show subcommands if the requested
+# verbosity level is greater than 1.  Otherwise, do nothing.
 verbose="${VERBOSE:-0}"
 if [ "$verbose" -gt '1' ]
 then
 	set -x
+	readonly v_flags='-v'
 	readonly x_flags='-x'
 elif [ "$verbose" -gt '0' ]
 then
 	set -x
+	readonly v_flags='-v'
 	readonly x_flags=''
 else
 	set +x
+	readonly v_flags=''
 	readonly x_flags=''
 fi
 
@@ -84,7 +87,11 @@ fi
 # Don't use cgo.  Use modules.
 export CGO_ENABLED='0' GO111MODULE='on'
 
-readonly build_flags="${BUILD_FLAGS:-$out_flags $par_flags $x_flags}"
+readonly build_flags="${BUILD_FLAGS:-$out_flags $par_flags\
+	$v_flags $x_flags}"
 
-# Don't use quotes with $build_flags to get word splitting.
+# Don't use quotes with flag variables to get word splitting.
+"$go" generate $v_flags $x_flags ./...
+
+# Don't use quotes with flag variables to get word splitting.
 "$go" build --ldflags "$ldflags" $build_flags

scripts/go-lint.sh → scripts/make/go-lint.sh

@@ -11,10 +11,8 @@ then
 	set -x
 fi
 
-exit_on_error="${EXITONERROR:-1}"
-
-# Set $EXITONERROR to zero to see all errors.
-if [ "$exitonerror" = '0' ]
+# Set $EXIT_ON_ERROR to zero to see all errors.
+if [ "${EXIT_ON_ERROR:-1}" = '0' ]
 then
 	set +e
 else