Make README more friendly

* reorder sections so we have a more newbie friendly reading flow:
  requirements -> building -> running

* add links to documentation

* drop mentions of autotools

* drop piglit references

* don't list dependencies, just point to Dockerfiles

* mention IGT containers

v2: typos, articles and better formatting (Rhys Kidd)

Cc: Petri Latvala <petri.latvala@intel.com>
Signed-off-by: Arkadiusz Hiler <arkadiusz.hiler@intel.com>
Reviewed-by: Rhys Kidd <rhyskidd@gmail.com>
Acked-by: Petri Latvala <petri.latvala@intel.com>

1 files changed, 89 insertions, 145 deletions

diff --git a/README.md b/README.md
index b8c4c5a8..a6a821c0 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 IGT GPU Tools
 =============
 
+
 Description
 -----------
 
@@ -12,200 +13,143 @@ complicated build procedures or specific testing environments to get useful
 results. Therefore, IGT GPU Tools includes low-level tools and tests
 specifically for development and testing of the DRM Drivers.
 
-IGT GPU Tools is split into several sections:
-
-**benchmarks/**
+Generated documentation for the latest master is published under
+<https://drm.pages.freedesktop.org/igt-gpu-tools/>.
 
-This is a collection of useful microbenchmarks that can be used to tune
-DRM code in relevant ways.
 
-The benchmarks require KMS to be enabled.  When run with an X Server
-running, they must be run as root to avoid the authentication
-requirement.
-
-Note that a few other microbenchmarks are in tests (like gem_gtt_speed).
-
-**tests/**
+Requirements
+------------
 
-This is a set of automated tests to run against the DRM to validate
-changes. Many of the tests have subtests, which can be listed by using
-the --list-subtests command line option and then run using the
---run-subtest option. If --run-subtest is not used, all subtests will
-be run. Some tests have futher options and these are detailed by using
-the --help option.
+See `Dockerfile.*` for up-to-date list of package names in Fedora and
+Debian.
 
-The test suite can be run using the run-tests.sh script available in
-the scripts directory. Piglit is used to run the tests and can either
-be installed from your distribution (if available), or can be
-downloaded locally for use with the script by running:
+If your distribution packages IGT you can also use your package manager to
+install the dependencies, e.g.:
 
-    ./scripts/run-tests.sh -d
+    # dnf builddep igt-gpu-tools
 
-run-tests.sh has options for filtering and excluding tests from test
-runs:
+But keep in mind that this may be slightly outdated and miss some
+recently added dependencies for building the current master.
 
-  -t <regex>      only include tests that match the regular expression
-  -x <regex>      exclude tests that match the regular expression
 
-Useful patterns for test filtering are described in the API
-documentation and the full list of tests and subtests can be produced
-by passing -l to the run-tests.sh script.
+Building
+--------
 
-Results are written to a JSON file and an HTML summary can also be
-created by passing -s to the run-tests.sh script. Further options are
-are detailed by using the -h option.
+Oneliner to get started:
 
+    $ meson build && ninja -C build
 
-If not using the script, piglit can be obtained from:
+Note that meson insist on separate build directories from the source tree.
 
-    git://anongit.freedesktop.org/piglit
+Running selfchecks for `lib/tests` and `tests/` is done with
 
-There is no need to build and install piglit if it is only going to be
-used for running i-g-t tests.
+    $ ninja -C build test
 
-Set the IGT_TEST_ROOT environment variable to point to the tests
-directory, or set the path key in the "igt" section of piglit.conf to
-the igt-gpu-tools root directory.
+Documentation is built using
 
-The tests in the i-g-t sources need to have been built already. Then we
-can run the testcases with (as usual as root, no other drm clients
-running):
+    $ ninja -C build igt-gpu-tools-doc
 
-    piglit-sources # ./piglit run igt <results-file>
 
-The testlist is built at runtime, so no need to update anything in
-piglit when adding new tests. See
+Running Tests
+-------------
 
-    piglit-sources $ ./piglit run -h
+In `tests/` you can find a set of automated tests to run against the DRM
+drivers to validate your changes. Many of the tests have subtests, which can
+be listed by using the `--list-subtests` command line option and then run
+using the --run-subtest option. If `--run-subtest` is not used, all subtests
+will be run. Some tests have further options and these are detailed by using
+the `--help` option.
 
-for some useful options.
+Most of the test must be run as a root and with no X or Wayland compositor
+running.
 
-Piglit only runs a default set of tests and is useful for regression
-testing. Other tests not run are:
-- tests that might hang the gpu, see HANG in Makefile.am
-- gem_stress, a stress test suite. Look at the source for all the
-  various options.
-- testdisplay is only run in the default mode. testdisplay has tons of
-  options to test different kms functionality, again read the source for
-  the details.
+    # build/tests/core_auth
+    IGT-Version: 1.24 (x86_64) (Linux: 5.3.0 x86_64)
+    Starting subtest: getclient-simple
+    Subtest getclient-simple: SUCCESS (0.001s)
+    Starting subtest: getclient-master-drop
+    Subtest getclient-master-drop: SUCCESS (0.000s)
+    Starting subtest: basic-auth
+    Subtest basic-auth: SUCCESS (0.000s)
+    Starting subtest: many-magics
+    Subtest many-magics: SUCCESS (0.000s)
 
-**lib/**
+    # build/tests/core_auth --run-subtest getclient-simple
+    IGT-Version: 1.24 (x86_64) (Linux: 5.3.0 x86_64)
+    Starting subtest: getclient-simple
+    Subtest getclient-simple: SUCCESS (0.000s)
 
-Common helper functions and headers used by the other tools.
 
-**man/**
+The test suite can be run using the `run-tests.sh` script available in the
+`scripts/` directory. To use it make sure that `igt_runner` is built, e.g.:
 
-Manpages, unfortunately rather incomplete.
+    meson -Drunner=enabled build && ninja -C build
 
-**tools/**
+`run-tests.sh` has options for filtering and excluding tests from test
+runs:
 
-This is a collection of debugging tools that had previously been
-built with the 2D driver but not shipped.  Some distros were hacking
-up the 2D build to ship them.  Instead, here's a separate package for
-people debugging the driver.
+    -t <regex>      only include tests that match the regular expression
+    -x <regex>      exclude tests that match the regular expression
 
-These tools generally must be run as root, except for the ones that just
-decode dumps.
+Useful patterns for test filtering are described in the [API
+documentation][API] and the full list of tests and subtests can be produced
+by passing `-l` to the `run-tests.sh` script. Further options are are
+detailed by using the `-h` option.
 
-**docs/**
+Results are written to a JSON file.
 
-Contains the automatically generated igt-gpu-tools libraries
-reference documentation in docs/reference/. You need to have the
-gtk-doc tools installed and use the "--enable-gtk-doc" configure flag
-to generate this API documentation.
+[API]: https://drm.pages.freedesktop.org/igt-gpu-tools/igt-gpu-tools-Core.html
 
-To regenerate the html files when updating documentation, use:
 
-    $ ninja -C build igt-gpu-tools-doc
+IGT Containers
+--------------
 
-If you've added/changed/removed a symbol or anything else that changes
-the overall structure or indexes, this needs to be reflected in
-igt-gpu-tools-sections.txt. Entirely new sections will also need to be
-added to igt-gpu-tools-docs.xml in the appropriate place.
+IGT is packed into nifty docker-compatible containers for ease of execution
+and to avoid having to install all the dependencies. You can use
+podman/docker to to run it on your system.
 
-**include/drm-uapi**
+Oneliner to get you started with the latest master:
 
-Imported DRM uapi headers from airlied's drm-next branch.
-These should be updated all together by executing "make
-headers_install" from that branch of the kernel and then
-copying the resulting ./usr/include/drm/*.h in and committing
-with a note of which commit on airlied's branch was used to
-generate them.
+    # podman run --rm --priviledged registry.freedesktop.org/drm/igt-gpu-tools/igt:master
 
 
-Requirements
+Other Things
 ------------
 
-This is a non-exhaustive list of package dependencies required for building
-the default configuration (package names may vary):
-
-	bison
-	gtk-doc-tools
-	flex
-	libcairo2-dev
-	libdrm-dev
-	libkmod-dev
-	libpixman-1-dev
-	libpciaccess-dev
-	libprocps-dev
-	libudev-dev
-	libunwind-dev
-	liblzma-dev
-	libdw-dev
-	python-docutils
-	x11proto-dri2-dev
-	xutils-dev
-
-The following dependencies are required for building chamelium support
-(package names may vary):
-
-	libxmlrpc-core-c3-dev
-	libudev-dev
-	libglib2.0-dev
-	libgsl-dev
-
-The following dependencies are requires for building audio support
-(package names may vary):
+### `benchmarks/`
 
-	libasound2-dev
-	libgsl-dev
+A collection of useful microbenchmarks that can be used to tune DRM code.
 
-See Dockerfiles.* for package names in different distributions.
-
-Meson build system support
---------------------------
-
-Currently we support both meson and automake as build systems, but meson is the
-recommended choice. Oneliner to get started:
+The benchmarks require KMS to be enabled.  When run with an X Server
+running, they must be run as root to avoid the authentication
+requirement.
 
-    $ mkdir build && meson build && cd build && ninja
+Note that a few other microbenchmarks are in tests (e.g. `gem_gtt_speed`).
 
-Note that meson insist on separate build directories from the source tree.
+### `tools/`
 
-Running selfchecks for lib/tests and tests/ is done with
+A collection of debugging tools. They generally must be run as root, except
+for the ones that just decode dumps.
 
-    $ ninja -C build test
+### `docs/`
 
-Note that this doesn't actually run the testcases in tests/: scripts/run-tests.sh
-should continue to be used for that.
+Contains the infrastructure to automatically generate igt-gpu-tools libraries
+reference documentation. You need to have the gtk-doc tools installed.
 
-Documentation is built using
+To regenerate the html files when updating documentation, use:
 
     $ ninja -C build igt-gpu-tools-doc
 
-Note that this needs meson v0.47 or later, earlier versions of meson do not
-track depencies correctly for the documentation build and need:
+If you've added/changed/removed a symbol or anything else that changes the
+overall structure or indexes you need to reflect the change in
+`igt-gpu-tools-sections.txt`. Entirely new sections also need to be added to
+`igt-gpu-tools-docs.xml` in the appropriate place.
 
-    $ ninja -C build && ninja -C build igt-gpu-tools-doc
+### `include/drm-uapi/`
 
-Note that there's a setup script similar to ./autogen.sh which creates a
-compatibility Makefile with a few useful default targets:
-
-    $ ./meson.sh [make-arguments]
-
-Releases for maintainers
-------------------------
-
-(1.14)
+Imported DRM uapi headers from airlied's drm-next branch.
 
-http://www.x.org/wiki/Development/Documentation/ReleaseHOWTO/
+These should be updated all together by executing `make headers_install` from
+that branch of the kernel and then copying the resulting
+`./usr/include/drm/*.h` in and committing with a note of which exact commit
+from airlied's branch was used to generate them.