[igt-dev] [PATCH i-g-t] README|CONTRIBUTING: Move to .md

* [igt-dev] [PATCH i-g-t] README|CONTRIBUTING: Move to .md
@ 2018-10-24 13:34 Daniel Vetter
  2018-10-24 17:04 ` Rodrigo Vivi
                   ` (2 more replies)
  0 siblings, 3 replies; 6+ messages in thread
From: Daniel Vetter @ 2018-10-24 13:34 UTC (permalink / raw)
  To: IGT development; +Cc: Daniel Vetter

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@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@lists.freedesktop.org>
+      Development mailing list for IGT GPU Tools <igt-dev@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@lists.freedesktop.org>
+      Intel GFX discussion <intel-gfx@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

_______________________________________________
igt-dev mailing list
igt-dev@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/igt-dev

^ permalink raw reply related	[flat|nested] 6+ messages in thread