[igt-dev] [PATCH i-g-t] README|CONTRIBUTING: Move to .md
Rodrigo Vivi
rodrigo.vivi at intel.com
Thu Oct 25 18:36:20 UTC 2018
On Thu, Oct 25, 2018 at 08:58:22AM +0200, Daniel Vetter wrote:
> On Wed, Oct 24, 2018 at 10:04:14AM -0700, Rodrigo Vivi wrote:
> > On Wed, Oct 24, 2018 at 03:34:21PM +0200, Daniel Vetter wrote:
> > > Looks so much better in the gitlab UI. Maybe we want to split out some
> > > of these README into subdirectories ...
> > >
> > > v2: Polish layout a bit. Changes are only whitespace, but README is so
> > > complicated reworked that git's rename detection doesn't spot the
> > > similarities anymore.
> > >
> > > Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> > > ---
> > > Note this needs Petri's earlier patch to apply cleanly.
> > > -Daniel
> > > ---
> > > CONTRIBUTING => CONTRIBUTING.md | 6 +-
> > > README | 202 ------------------------------
> > > README.md | 210 ++++++++++++++++++++++++++++++++
> > > 3 files changed, 213 insertions(+), 205 deletions(-)
> > > rename CONTRIBUTING => CONTRIBUTING.md (95%)
> > > delete mode 100644 README
> > > create mode 100644 README.md
> > >
> > > diff --git a/CONTRIBUTING b/CONTRIBUTING.md
> > > similarity index 95%
> > > rename from CONTRIBUTING
> > > rename to CONTRIBUTING.md
> > > index 1a68fcf5cc9c..27c8e7967b93 100644
> > > --- a/CONTRIBUTING
> > > +++ b/CONTRIBUTING.md
> > > @@ -8,7 +8,7 @@ A short list of contribution guidelines:
> > > - Please submit patches formatted with git send-email/git format-patch or
> > > equivalent to:
> > >
> > > - Development mailing list for IGT GPU Tools <igt-dev at lists.freedesktop.org>
> > > + Development mailing list for IGT GPU Tools <igt-dev at lists.freedesktop.org>
> > >
> > > For a transition period patches are accepted on both the igt-dev mailing list
> > > and the former intel-gfx mailing list (with the appropriate patch
> > > @@ -18,13 +18,13 @@ A short list of contribution guidelines:
> > > have a need to do so, as they will get deduplicated so they only appear and
> > > are tested in one Patchwork instance.
> > >
> > > - Intel GFX discussion <intel-gfx at lists.freedesktop.org>
> > > + Intel GFX discussion <intel-gfx at lists.freedesktop.org>
> > >
> > > Please use --subject-prefix="PATCH i-g-t" so IGT patches are easily
> > > identified in the massive amount mails on intel-gfx. To ensure this is always
> > > done, meson.sh (and autogen.sh) will run:
> > >
> > > - git config format.subjectprefix "PATCH i-g-t"
> > > + git config format.subjectprefix "PATCH i-g-t"
> > >
> > > on its first invocation.
> > >
> > > diff --git a/README b/README
> > > deleted file mode 100644
> > > index 78d14060dccd..000000000000
> > > --- a/README
> > > +++ /dev/null
> > > @@ -1,202 +0,0 @@
> > > -IGT GPU Tools
> > > -=============
> > > -
> > > -Description
> > > ------------
> > > -
> > > -IGT GPU Tools is a collection of tools for development and testing of the DRM
> > > -drivers. There are many macro-level test suites that get used against the
> > > -drivers, including xtest, rendercheck, piglit, and oglconform, but failures from
> > > -those can be difficult to track down to kernel changes, and many require
> > > -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.
> > > -
> > > -debugger/
> > > - This tool is to be used to do shader debugging. It acts like a
> > > - debug server accepting connections from debug clients such as
> > > - mesa. The connections is made with unix domain sockets, and at some
> > > - point it would be nice if this directory contained a library for
> > > - initiating connections with debug clients..
> > > -
> > > - The debugger must be run as root: "sudo debugger/eudb"
> > > -
> > > -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:
> > > -
> > > - $ make clean -C docs && make -C docs
> > > -
> > > - 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.
> > > -
> > > -
> > > -Requirements
> > > -------------
> > > -
> > > -This is a non-exhaustive list of package dependencies required for building
> > > -the default configuration (package names may vary):
> > > -
> > > - gtk-doc-tools
> > > - libcairo2-dev
> > > - libdrm-dev
> > > - libkmod-dev
> > > - libpixman-1-dev
> > > - libpciaccess-dev
> > > - libprocps-dev
> > > - libunwind-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):
> > > -
> > > - libasound2-dev
> > > - libgsl-dev
> > > -
> > > -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
> > > -
> > > -Note that meson insist on separate build directories from the source tree.
> > > -
> > > -Running selfchecks for lib/tests and tests/ is done with
> > > -
> > > -$ cd build && ninja 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
> > > -
> > > -$ cd build && ninja && ninja igt-gpu-tools-doc
> > > -
> > > -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)
> > > -
> > > -http://www.x.org/wiki/Development/Documentation/ReleaseHOWTO/
> > > diff --git a/README.md b/README.md
> > > new file mode 100644
> > > index 000000000000..dcff03efdbac
> > > --- /dev/null
> > > +++ b/README.md
> > > @@ -0,0 +1,210 @@
> > > +IGT GPU Tools
> > > +=============
> > > +
> > > +Description
> > > +-----------
> > > +
> > > +IGT GPU Tools is a collection of tools for development and testing of the DRM
> > > +drivers. There are many macro-level test suites that get used against the
> > > +drivers, including xtest, rendercheck, piglit, and oglconform, but failures from
> > > +those can be difficult to track down to kernel changes, and many require
> > > +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
> >
> > ```bash
> >
> > > +
> > > + piglit-sources $ ./piglit run -h
> > > +
> >
> > ```
> >
> > I believe all blocks with command lines could be in the markdown block
> > like this ```bash or something like that.
>
> I tried to do that (you need 4 spaces of indent at least). Did I miss one?
> Or I'm not entirely following ...
ah cool... I didn't know this possibility.
just ignore me ;)
Thanks,
Rodrigo
> -Daniel
>
> >
> > But this can be done in a follow-up since it gets easier to review
> > I think...
> >
> > so:
> >
> > Reviewed-by: Rodrigo Vivi <rodrigo.vivi at intel.com>
> >
> >
> > > +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.
> > > +
> > > +**debugger/**
> > > +
> > > +This tool is to be used to do shader debugging. It acts like a
> > > +debug server accepting connections from debug clients such as
> > > +mesa. The connections is made with unix domain sockets, and at some
> > > +point it would be nice if this directory contained a library for
> > > +initiating connections with debug clients..
> > > +
> > > +The debugger must be run as root: "sudo debugger/eudb"
> > > +
> > > +**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:
> > > +
> > > + $ make clean -C docs && make -C docs
> > > +
> > > +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.
> > > +
> > > +
> > > +Requirements
> > > +------------
> > > +
> > > +This is a non-exhaustive list of package dependencies required for building
> > > +the default configuration (package names may vary):
> > > +
> > > + gtk-doc-tools
> > > + libcairo2-dev
> > > + libdrm-dev
> > > + libkmod-dev
> > > + libpixman-1-dev
> > > + libpciaccess-dev
> > > + libprocps-dev
> > > + libunwind-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):
> > > +
> > > + libasound2-dev
> > > + libgsl-dev
> > > +
> > > +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
> > > +
> > > +Note that meson insist on separate build directories from the source tree.
> > > +
> > > +Running selfchecks for lib/tests and tests/ is done with
> > > +
> > > + $ cd build && ninja 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
> > > +
> > > + $ cd build && ninja && ninja igt-gpu-tools-doc
> > > +
> > > +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)
> > > +
> > > +http://www.x.org/wiki/Development/Documentation/ReleaseHOWTO/
> > > --
> > > 2.19.1
> > >
> > > _______________________________________________
> > > igt-dev mailing list
> > > igt-dev at lists.freedesktop.org
> > > https://lists.freedesktop.org/mailman/listinfo/igt-dev
>
> --
> Daniel Vetter
> Software Engineer, Intel Corporation
> http://blog.ffwll.ch
> _______________________________________________
> igt-dev mailing list
> igt-dev at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/igt-dev
More information about the igt-dev
mailing list