[igt-dev] [PATCH i-g-t] Make README more friendly

Fri Oct 4 11:57:14 UTC 2019

On Fri, 04 Oct 2019, Petri Latvala <petri.latvala at intel.com> wrote:
> 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.

FWIW, git format-patch --break-rewrites option with suitable N/M values
to force a rewite patch might be helpful in cases like these.

BR,
Jani.

>
> 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
>> 
> _______________________________________________
> igt-dev mailing list
> igt-dev at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/igt-dev

-- 
Jani Nikula, Intel Open Source Graphics Center