[igt-dev] [PATCH i-g-t] README|CONTRIBUTING: Move to .md
Daniel Vetter
daniel.vetter at ffwll.ch
Wed Oct 24 13:34:21 UTC 2018
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
+
+ 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/
--
2.19.1
More information about the igt-dev
mailing list