[igt-dev] [PATCH i-g-t] Make README more friendly
Petri Latvala
petri.latvala at intel.com
Fri Oct 4 09:24:38 UTC 2019
On Thu, Oct 03, 2019 at 04:06:57PM +0300, Arkadiusz Hiler wrote:
> * 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
>
> Cc: Petri Latvala <petri.latvala at intel.com>
> Signed-off-by: Arkadiusz Hiler <arkadiusz.hiler at intel.com>
The diff is horrible to read but the resulting README LGTM.
Acked-by: Petri Latvala <petri.latvala at intel.com>
> ---
> README.md | 280 ++++++++++++++++++++++--------------------------------
> 1 file changed, 112 insertions(+), 168 deletions(-)
>
> diff --git a/README.md b/README.md
> index b8c4c5a8..b295dc3e 100644
> --- a/README.md
> +++ b/README.md
> @@ -1,6 +1,7 @@
> IGT GPU Tools
> =============
>
> +
> Description
> -----------
>
> @@ -12,173 +13,31 @@ 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/**
> -
> -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/**
> -
> -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.
> -
> -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:
> -
> - ./scripts/run-tests.sh -d
> -
> -run-tests.sh has options for filtering and excluding tests from test
> -runs:
> -
> - -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.
> -
> -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.
> -
> -
> -If not using the script, piglit can be obtained from:
> -
> - git://anongit.freedesktop.org/piglit
> -
> -There is no need to build and install piglit if it is only going to be
> -used for running i-g-t tests.
> -
> -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.
> -
> -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):
> -
> - 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
> -
> - piglit-sources $ ./piglit run -h
> -
> -for some useful options.
> -
> -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.
> -
> -**lib/**
> -
> -Common helper functions and headers used by the other tools.
> -
> -**man/**
> -
> -Manpages, unfortunately rather incomplete.
> -
> -**tools/**
> -
> -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.
> -
> -These tools generally must be run as root, except for the ones that just
> -decode dumps.
> -
> -**docs/**
> -
> -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.
> -
> -To regenerate the html files when updating documentation, use:
> -
> - $ ninja -C build igt-gpu-tools-doc
> -
> -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.
> -
> -**include/drm-uapi**
> -
> -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.
> +Generated documentation for the latest master is published under
> +<https://drm.pages.freedesktop.org/igt-gpu-tools/>.
>
>
> Requirements
> ------------
>
> -This is a non-exhaustive list of package dependencies required for building
> -the default configuration (package names may vary):
> +See `Dockerfiles.*` for up-to-date list of packages names in Fedora and
> +Debian.
>
> - 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
> +If your distribution packages IGT you can also use your package manager to
> +install the dependencies, e.g.:
>
> -The following dependencies are required for building chamelium support
> -(package names may vary):
> + # dnf builddep igt-gpu-tools
>
> - libxmlrpc-core-c3-dev
> - libudev-dev
> - libglib2.0-dev
> - libgsl-dev
> +But keep in mind that this may be slightly outdated and miss some
> +recently added dependencies for building the current master.
>
> -The following dependencies are requires for building audio support
> -(package names may vary):
>
> - libasound2-dev
> - libgsl-dev
> +Building
> +--------
>
> -See Dockerfiles.* for package names in different distributions.
> +Oneliner to get started:
>
> -Meson build system support
> ---------------------------
> -
> -Currently we support both meson and automake as build systems, but meson is the
> -recommended choice. Oneliner to get started:
> -
> - $ mkdir build && meson build && cd build && ninja
> + $ meson build && ninja -C build
>
> Note that meson insist on separate build directories from the source tree.
>
> @@ -186,26 +45,111 @@ Running selfchecks for lib/tests and tests/ is done with
>
> $ ninja -C build test
>
> -Note that this doesn't actually run the testcases in tests/: scripts/run-tests.sh
> -should continue to be used for that.
> -
> Documentation is built using
>
> $ 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:
>
> - $ ninja -C build && ninja -C build igt-gpu-tools-doc
> +Running Tests
> +-------------
>
> -Note that there's a setup script similar to ./autogen.sh which creates a
> -compatibility Makefile with a few useful default targets:
> +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.
>
> - $ ./meson.sh [make-arguments]
> +Most of the test must be run as a root and with no X or Wayland compositor
> +running.
>
> -Releases for maintainers
> -------------------------
> + # 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)
>
> -(1.14)
> + # 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)
>
> -http://www.x.org/wiki/Development/Documentation/ReleaseHOWTO/
> +
> +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.:
> +
> + meson -Drunner=enabled build && ninja -C build
> +
> +`run-tests.sh` has options for filtering and excluding tests from test
> +runs:
> +
> + -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][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.
> +
> +Results are written to a JSON file.
> +
> +[API]: https://drm.pages.freedesktop.org/igt-gpu-tools/igt-gpu-tools-Core.html
> +
> +
> +IGT Containers
> +--------------
> +
> +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.
> +
> +Oneliner to get you started with the latest master:
> +
> + # podman run --rm --priviledged registry.freedesktop.org/drm/igt-gpu-tools/igt:master
> +
> +
> +Other Things
> +------------
> +
> +### `benchmarks/`
> +
> +A collection of useful microbenchmarks that can be used to tune DRM code.
> +
> +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 (e.g. `gem_gtt_speed`).
> +
> +### `tools/`
> +
> +A collection of debugging tools. They generally must be run as root, except
> +for the ones that just decode dumps.
> +
> +### `docs/`
> +
> +Contains the infrastracture to automatically generate igt-gpu-tools libraries
> +reference documentation. You need to have the gtk-doc tools installed.
> +
> +To regenerate the html files when updating documentation, use:
> +
> + $ ninja -C build igt-gpu-tools-doc
> +
> +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.
> +
> +### `include/drm-uapi/`
> +
> +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 exact commit
> +from the airlied's branch was used to generate them.
> --
> 2.21.0
>
More information about the igt-dev
mailing list