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

[Daniel Vetter <daniel@ffwll.ch>]

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@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
> 
> ```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 ...
-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@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@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@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/igt-dev