[xorg-doc - Cygwin XOrg documentation] branch master, updated. 6c2a1422c13ee772d087bccec6febe522ce3cbbd

[xorg-doc - Cygwin XOrg documentation] branch master, updated. 6c2a1422c13ee772d087bccec6febe522ce3cbbd

[jturney]

https://sourceware.org/git/gitweb.cgi?p=cygwin-apps/xorg-doc.git;h=6c2a1422c13ee772d087bccec6febe522ce3cbbd

commit 6c2a1422c13ee772d087bccec6febe522ce3cbbd
Author: Jon Turney <jon.turney@dronecode.org.uk>
Date:   Fri Jun 29 18:05:46 2018 +0100

    Adjust build instructions for meson

https://sourceware.org/git/gitweb.cgi?p=cygwin-apps/xorg-doc.git;h=c7a6be5bcaef47a8da58b7104cdf886079ab42d1

commit c7a6be5bcaef47a8da58b7104cdf886079ab42d1
Author: Jon Turney <jon.turney@dronecode.org.uk>
Date:   Fri Jun 29 18:04:56 2018 +0100

    Update for cygport source package subdir
    
    Cygport hasn't dropped source package contents directly in /usr/src for a while
    Also tweak examples for X server versions >=1.10

https://sourceware.org/git/gitweb.cgi?p=cygwin-apps/xorg-doc.git;h=aa2c2be97e52b1bef2c69299b9fa289ff01d5f7b

commit aa2c2be97e52b1bef2c69299b9fa289ff01d5f7b
Author: Jon Turney <jon.turney@dronecode.org.uk>
Date:   Fri Jun 29 18:01:50 2018 +0100

    Remove mention of Xfake server, removed upsteam

https://sourceware.org/git/gitweb.cgi?p=cygwin-apps/xorg-doc.git;h=3e82a3aefdb60a7792406bbc7eb7fc9e1042fe88

commit 3e82a3aefdb60a7792406bbc7eb7fc9e1042fe88
Author: Jon Turney <jon.turney@dronecode.org.uk>
Date:   Fri Jun 29 18:00:44 2018 +0100

    Drop discussion of native drawing engine
    
    Also, mark discussion of primary fb engine as historical

https://sourceware.org/git/gitweb.cgi?p=cygwin-apps/xorg-doc.git;h=bcd4892b4257b8b0e5948f963957f16a31b6dd94

commit bcd4892b4257b8b0e5948f963957f16a31b6dd94
Author: Jon Turney <jon.turney@dronecode.org.uk>
Date:   Fri Jun 29 16:41:52 2018 +0100

    Update prerequisites for xorgproto and meson
    
    Also remove historical note about libXfont linkage


Diff:
---
 cg/cygwin-x-cg.xml                     |    6 +--
 cg/programming-cross.xml               |   18 +++---
 cg/programming-distribution.xml        |    6 +-
 cg/programming-native.xml              |   80 +++++-------------------
 cg/programming-obtaining-source.xml    |   33 +++-------
 cg/programming-prerequisites.xml       |  108 ++------------------------------
 cg/programming-server-architecture.xml |   35 +++--------
 cg/programming-tree-layout.xml         |   14 +---
 8 files changed, 57 insertions(+), 243 deletions(-)

diff --git a/cg/cygwin-x-cg.xml b/cg/cygwin-x-cg.xml
index 8326d1c..dafad5e 100644
--- a/cg/cygwin-x-cg.xml
+++ b/cg/cygwin-x-cg.xml
@@ -34,10 +34,6 @@
 
 <!-- Project entities -->
 <!ENTITY project-path-devel "~/xserver">
-<!ENTITY project-path-xc "&project-path-devel;/xc">
-<!ENTITY project-path-build "&project-path-devel;/build">
-<!ENTITY project-path-build-std "&project-path-build;/std">
-<!ENTITY project-path-build-debug "&project-path-build;/debug">
 <!ENTITY project-path-stagingdir "/stagingdir">
 <!ENTITY project-path-bindistdir "/bindistdir">
 <!ENTITY project-path-commondistdir "/commondist">
@@ -155,7 +151,7 @@ Distribution">
 
 <legalnotice id="legal-notice">
 <blockquote id="legal-notice-quote"><para>
-Copyright (C) 2004 Harold L Hunt II.  Copyright (C) 2009-2017 Jon Turney.
+Copyright (C) 2004 Harold L Hunt II.  Copyright (C) 2009-2018 Jon Turney.
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3
 or any later version published by the Free Software Foundation;
diff --git a/cg/programming-cross.xml b/cg/programming-cross.xml
index b10488d..9ad1dfa 100644
--- a/cg/programming-cross.xml
+++ b/cg/programming-cross.xml
@@ -32,28 +32,28 @@ compiling host, rather than on your native &cygwin; host.</para>
 
 <listitem>
 <para>When configuring, you must pass
-<parameter>--target=i686-pc-cygwin</parameter> to <command>./configure</command> to
-cause the build system to build for the target, &cygwin;,
-platform:</para>
+<parameter>--cross-file=<replaceable>crossfile</replaceable></parameter> ,
+pointing to a suitable cross file, to <command>meson</command>, to cause the
+build system to build for the target, &cygwin;, platform:</para>
 </listitem>
 
 <listitem>
-<para>When installing a build, you must
-pass <parameter>DESTDIR=&project-path-stagingdir;</parameter> to <command>make install</command> to
-install the target platform build into <filename
+<para>When installing a build, you must use
+<parameter>DESTDIR=&project-path-stagingdir;</parameter> with <command>ninja
+install</command> to install the target platform build into <filename
 class="directory">&project-path-stagingdir;</filename>.
 </para>
 
 <tip>
-<para>Never run <command>make install</command> on your
-host platform without the <parameter>DESTDIR</parameter> parameter, as
+<para>Never run <command>ninja install</command> on your
+host platform without the <parameter>DESTDIR</parameter>, as
 that will cause the &cygwin; build of &x-window-system; to be installed over top
 of your local X Window System installation, which would completely
 destroy your host system's X Window System installation.</para>
 </tip>
 
 <para>OR, when configuring, you can pass
-<parameter>--prefix=&project-path-stagingdir;</parameter> to <command>./configure</command> to
+<parameter>--prefix=&project-path-stagingdir;</parameter> to
 cause the build system to be configured to install the target platform build into
 <filename class="directory">&project-path-stagingdir;</filename>.
 This avoids the possibilty of installing over the native installation, at the
diff --git a/cg/programming-distribution.xml b/cg/programming-distribution.xml
index 2d07e28..aba43f4 100644
--- a/cg/programming-distribution.xml
+++ b/cg/programming-distribution.xml
@@ -23,11 +23,11 @@ sources, cygwin-ports git or an X.Org release tarball instead.
 </listitem>
 
 <listitem>
-<para>Invoke cygport on the .cygport file contained in the source package installed above.  This will create the source and binary packages <filename>xorg-server-n.n.n-X-src.tar.bz2</filename> and <filename>xorg-server-n.n.n-X.tar.bz2</filename>
+<para>Invoke cygport on the .cygport file contained in the source package installed above.  This will create the source and binary packages <filename>xorg-server-n.nn.n-X-src.tar.bz2</filename> and <filename>xorg-server-n.nn.n-X.tar.bz2</filename>
 
 <screen>
-&cygwin-bash-prompt; /usr/src
-$ cygport xorg-server-x.x.x-x.cygport all
+&cygwin-bash-prompt; /usr/src/xorg-server-x.xx.x-x.src/
+$ cygport xorg-server-x.xx.x-x.cygport all
 </screen>
 </para>
 
diff --git a/cg/programming-native.xml b/cg/programming-native.xml
index bde9d51..ce21c3e 100644
--- a/cg/programming-native.xml
+++ b/cg/programming-native.xml
@@ -6,14 +6,6 @@
 <sect2 id="prog-compiling">
 <title>Compiling the Source Code</title>
 
-<!-- BEGIN Standard build -->
-
-<sect3 id="prog-compiling-standard">
-<title>Standard Build</title>
-
-<para>Follow these steps to create a standard, non-debug,
-build:</para>
-
 <para>Change the current directory to your &x-window-system; development
 directory:</para>
 
@@ -22,71 +14,31 @@ directory:</para>
 $ cd &project-path-devel;
 
 &cygwin-bash-prompt; &project-path-devel;
-$ ./configure --prefix=/usr --with-log-dir=/var/log
+$ meson _build --prefix=/usr
 [lots of output]
 
 &cygwin-bash-prompt; &project-path-devel;
-$ make
+$ ninja -C _build
 [lots more output]
 </screen>
 
-<para>Standard build is now complete.</para>
+<para>The build is now complete.</para>
 
 <note>
 <para>
-You may wish to consult the .cygport file for the current ./configure flags used
+You may wish to consult the .cygport file for the current configuration flags used
 in distributed packages
 </para>
 </note>
 
 <note>
 <para>
-The unpacked source occupies approximately 80MB of disk space.
-Building the source requires approximately an additional 160MB.
-On my ageing 2.2MHz Athlon64 3500+, a full build takes about 20 minutes.
+The unpacked source occupies approximately 30MB of disk space.
+Building the source requires approximately an additional 220MB.
+On my quad-core 3.4GHz i7-4770, a full build takes about 1 minute.
 </para>
 </note>
 
-<note>
-<para>
-If you wish to keep build products separate from the source, you may
-run configure from a separate build directory.</para>
-</note>
-
-</sect3>
-
-<!-- END Standard build -->
-
-<!-- BEGIN Debug build -->
-
-<sect3 id="prog-compiling-debug">
-<title>Debug Build</title>
-
-<para>Follow these steps to create a build with debugging
-information:</para>
-
-<para>Change the current directory to your &x-window-system; development
-directory:</para>
-
-<screen>
-&cygwin-bash-prompt; ~
-$ cd &project-path-devel;
-
-&cygwin-bash-prompt; &project-path-devel;
-$ ./configure --prefix=/usr --with-log-dir=/var/log --enable-debug CFLAGS="-g -O0"
-[lots of output]
-
-&cygwin-bash-prompt; &project-path-devel;
-$ make
-[lots more output]
-</screen>
-
-<para>Debug build is now complete.</para>
-
-</sect3>
-
-<!-- END Debug build -->
-
 </sect2>
 
 <!-- END Compiling the source -->
@@ -101,7 +53,7 @@ $ make
 <orderedlist numeration="arabic">
 
 <listitem>
-<para>Change the current directory to your &x-window-system; build
+<para>Change the current directory to your &x-window-system; development
 directory:</para>
 
 <screen>
@@ -116,7 +68,7 @@ $
 <para>Invoke the hw/xwin/Xwin executable:</para>
 <screen>
 &cygwin-bash-prompt; &project-path-devel;
-$ hw/xwin/XWin
+$ _build/hw/xwin/XWin
 </screen>
 <para>The X server you have built will now attempt to run.</para>
 </listitem>
@@ -141,25 +93,25 @@ man pages.
 <orderedlist numeration="arabic">
 
 <listitem>
-<para>Change the current directory to your desired &x-window-system; build
+<para>Change the current directory to your &x-window-system; development
 directory:</para>
 
 <screen>
 &cygwin-bash-prompt; ~
-$ cd &project-path-build;/<replaceable>build-prefix</replaceable>
+$ cd &project-path-devel;
 
-&cygwin-bash-prompt; &project-path-build;/<replaceable>build-prefix</replaceable>
-$ 
+&cygwin-bash-prompt; &project-path-devel;
+$
 </screen>
 </listitem>
 
 <listitem>
-<para>Make the <userinput>install</userinput> target, which installs
+<para>Use the <userinput>install</userinput> target, which installs
 everything:</para>
 
 <screen>
-&cygwin-bash-prompt; &project-path-build;/<replaceable>build-prefix</replaceable>
-$ make install
+&cygwin-bash-prompt; &project-path-devel;
+$ ninja -C _build install
 </screen>
 </listitem>
 
diff --git a/cg/programming-obtaining-source.xml b/cg/programming-obtaining-source.xml
index 9865a31..d178105 100644
--- a/cg/programming-obtaining-source.xml
+++ b/cg/programming-obtaining-source.xml
@@ -39,20 +39,21 @@ The sources can unpacked and prepared using cygport as follows:
 
 <screen>
 &cygwin-bash-prompt; ~
-$ cd /usr/src
+$ cd /usr/src/xorg-server-n.nn.n-n.src
 
-&cygwin-bash-prompt; /usr/src
-$ cygport xorg-server-n.n.n-n.cygport prep
+&cygwin-bash-prompt; /usr/src/xorg-server-n.nn.n-n.src
+$ cygport xorg-server-n.nn.n-n.cygport prep
 [lots of output as archive is unpacked and patches applied]
 
-$ cygport xorg-server-n.n.n-n.cygport compile
+&cygwin-bash-prompt; /usr/src/xorg-server-n.nn.n-n.src
+$ cygport xorg-server-n.nn.n-n.cygport compile
 [lots of output as source is configured and built]
 
-&cygwin-bash-prompt; /usr/src
-$ cd xorg-server-n.n.n-n/src/xorg-server-n.n.n/
+&cygwin-bash-prompt; /usr/src/xorg-server-n.nn.n-n.src
+$ cd xorg-server-n.nn.n-n/src/xorg-server-n.nn.n/
 [navigate to the source directory]
 
-&cygwin-bash-prompt; /usr/src/xorg-server-n.n.n-n/src/xorg-server-n.n.n/
+&cygwin-bash-prompt; /usr/src/xorg-server-n.nn.n-n/src/xorg-server-n.nn.n/
 $
 </screen>
 
@@ -65,14 +66,6 @@ Alternatively you may manually untar the archive and apply any patches
 
 <note>
 <para>
-It is necessary to run the package's autogen.sh script to
-regenerate the configure script and Makefiles if the patches modify the
-autoconf or automake source files
-</para>
-</note>
-
-<note>
-<para>
 For details of using cygport to generate packages for distribution, see
 <xref linkend="prog-distribution"></xref>
 </para>
@@ -135,13 +128,7 @@ $ git clone git://anongit.freedesktop.org/git/xorg/xserver
 You will probably want to look at the .cygport file in the source
 package obtained in <xref linkend="prog-source-cygwin-setup"/> and
 check you understand if you need to use the configuration options
-used there. For example:
-</para>
-
-<para>
-<screen>
-$ ./configure --prefix=/usr --with-log-dir=/var/log
-</screen>
+used there.
 </para>
 
 <para>
@@ -160,7 +147,7 @@ cgit interface to the X.Org tree
 </ulink>.
 Most of the Cygwin/X-specific code is in the
 <ulink url="http://cgit.freedesktop.org/xorg/xserver/tree/hw/xwin">
-xserver/hw/xwin</ulink> 
+xserver/hw/xwin</ulink>
 directory.
 </para>
 
diff --git a/cg/programming-prerequisites.xml b/cg/programming-prerequisites.xml
index f0fd3ef..a08fcef 100644
--- a/cg/programming-prerequisites.xml
+++ b/cg/programming-prerequisites.xml
@@ -20,25 +20,16 @@ selected packages.</para>
 <listitem>
 <para>Required tools:</para>
 <para>
-autoconf,
-automake,
 binutils,
 bison,
-bzip2,
 cygport,
-diffutils,
-fileutils,
-findutils,
 flex,
-gawk,
 gcc-core,
 git,
-libtool,
-make,
-patch,
+meson,
+ninja,
 pkg-config,
 python3,
-sed,
 tar
 </para>
 </listitem>
@@ -46,27 +37,8 @@ tar
 <listitem>
 <para>Required protocol headers:</para>
 <para>
-bigreqsproto,
-compositeproto,
-damageproto,
-dmxproto,
-fixesproto,
-fontsproto,
-glproto,
-inputproto,
-kbproto,
-presentproto,
-randrproto,
-recordproto,
-renderproto,
-resourceproto,
-scrnsaverproto,
 windowsdriproto,
-xcmiscproto,
-xextproto,
-xf86bigfontproto,
-xineramaproto,
-xproto
+xorgproto
 </para>
 </listitem>
 
@@ -77,7 +49,9 @@ libdmx-devel,
 libfontenc-devel,
 libfreetype-devel,
 libGL-devel,
+libnettle-devel,
 libpixman1-devel,
+libtirpc-devel,
 libX11-devel,
 libXRes-devel,
 libXau-devel,
@@ -102,7 +76,7 @@ libxcb-shape-devel,
 libxcb-util-devel,
 libxcb-xkb-devel,
 libxkbfile-devel,
-zlib
+zlib-devel
 </para>
 </listitem>
 
@@ -112,7 +86,6 @@ zlib
 font-util,
 khronos-opengl-registry,
 python3-lxml,
-xorg-util-macros,
 xtrans
 </para>
 </listitem>
@@ -130,80 +103,11 @@ xorg-sgml-doctools
 
 </itemizedlist>
 
-<note>
-<para>
-The /usr/share/doc/Cygwin/xorg-server-n.n.n.README file installed with the X server
-binary package lists up-to-date runtime and build requirements.
-</para>
-</note>
-
 <tip>
 <para>Use <command>setup -q -P<replaceable>packagename</replaceable>,<replaceable>packagename</replaceable>,<replaceable>etc.</replaceable></command> to quickly install the
 required packages.</para>
 </tip>
 
-
-</sect2>
-
-<sect2 id="prog-compiling-environment-setup">
-<title>Compilation environment setup</title>
-
-<sect3 id="prog-compiling-libXfont-linkage-issue">
-<title>libXfont linkage issue</title>
-
-<note>
-<para>
-As of libXfont 1.5 and X server 1.16, the linkage issue discussed here should be
-resolved.  This section is retained for information only.
-</para>
-</note>
-
-<para>
-libXfont must be statically linked for the server to start correctly, otherwise
-it fails with errors loading all fonts, including the mandatory fixed font.
-</para>
-
-<para>
-This is due to limitations of Cygwin's current weak symbol handling, which requires
-static linking to work correctly.  For example, in libXfont the RegisterFPEFunctions
-function is defined weak and should be overloaded with RegisterFPEFunctions defined
-in dix/dixfont.c in the xserver.
-However, such overloading will only currently work for Cygwin when libXfont is statically
-linked with the X server, and not as a shared libary.
-</para>
-
-<para>
-If Cygwin's libXfont-devel package contains a shared library stub, /usr/lib/libXFont.dll.a,
-when building the X server, you must prepare your compilation environment so that the libXfont
-shared libary stub is not linked with.
-</para>
-
-<para>
-A quick and dirty way of achieving this is to move libXFont.la and libXfont.dll.a
-aside whilst building the X server.
-</para>
-
-<para>
-<screen>
-mv /usr/lib/libXFont.la    /usr/lib/libXFont.la.old
-mv /usr/lib/libXFont.dll.a /usr/lib/libXFont.dll.a.old
-</screen>
-</para>
-
-<para>
-A cleaner way is to generate a customized .pc file for libXfont and arrange for that
-to be in your PKG_CONFIG_PATH when ./configuring the X server. For example:
-</para>
-
-<para>
-<screen>
-sed -e 's| -lXfont| /usr/lib/libXfont.a|' /usr/lib/pkgconfig/xfont.pc > ~/xfont.pc
-export PKG_CONFIG_PATH=~:$PKG_CONFIG_PATH
-</screen>
-</para>
-
-</sect3>
-
 </sect2>
 
 <!-- END Required packages -->
diff --git a/cg/programming-server-architecture.xml b/cg/programming-server-architecture.xml
index 65e6467..5ad5085 100644
--- a/cg/programming-server-architecture.xml
+++ b/cg/programming-server-architecture.xml
@@ -144,11 +144,10 @@ cause an access violation, crashing the &project; X Server.</para>
 
 <para>The &project; X Server uses several methods of drawing graphics
 on the display device; each of these different drawing methods is
-referred to as an engine.  Each of the engines can be classified as
-either a Shadow FB engine, a Native GDI engine, or as a Primary FB
-engine.  It should be noted that the Primary FB engine is deprecated
-and is discussed here only for completeness.  The engines are
-discussed in the following sections, in order of importance.</para>
+referred to as an engine.
+
+It should be noted that the Primary FB engine is historical
+and is discussed here only for completeness.</para>
 
 <!-- BEGIN Shadow Drawing -->
 
@@ -164,36 +163,20 @@ framebuffer</glossterm> with periodic updates of the <glossterm
 linkend="gloss-primary-framebuffer">primary
 framebuffer</glossterm>.</para>
 
-</sect3>
-
-<!-- END Shadow Drawing -->
-
-<!-- BEGIN Native Drawing -->
-
-<sect3 id="prog-server-architecture-engines-native">
-<title>&title-prog-server-architecture-engines-native;</title>
-
-<para>The Native GDI engine will eventually translate individual X
-graphics calls into their GDI equivalent.  Some X graphics calls do
-not translate directly to a GDI call so they may be passed through the
-MI layer to change them into a serious of lower level calls that are
-supported.  Currently, the Native GDI engine passes all X graphics
-calls through the MI layer to convert them into three functions:
-<function>FillSpans</function>, <function>GetSpans</function>, and
-<function>SetSpans</function>.  The functionality of those three
-functions, as of 2001-10-28, is limited to the functionality needed to
-draw the familiar X background pattern upon X Server startup.</para>
+<para>
+Currently, shadow FB engines exist using DirectDraw4 and GDI.
+</para>
 
 </sect3>
 
-<!-- END Native Drawing -->
+<!-- END Shadow Drawing -->
 
 <!-- BEGIN Primary Drawing -->
 
 <sect3 id="prog-server-architecture-engines-primary">
 <title>&title-prog-server-architecture-engines-primary;</title>
 
-<para>The Primary FB engine is deprecated.  Primary FB works in the
+<para>The Primary FB engine worked in the
 same manner that the original &project; X Server worked, namely, it
 uses <function>IDirectDrawSurface_Lock</function> to obtain a pointer
 to the <glossterm linkend="gloss-primary-framebuffer">primary
diff --git a/cg/programming-tree-layout.xml b/cg/programming-tree-layout.xml
index bb847a5..3655e32 100644
--- a/cg/programming-tree-layout.xml
+++ b/cg/programming-tree-layout.xml
@@ -42,11 +42,6 @@ Unlike Xnest it supports modern X extensions such as Composite, Damage, randr, e
 </para>
 </listitem>
 
-<listitem>
-<para><filename class="directory">fake</filename> contains the Xfake X Server.
-xfake is similar to xvfb, but discards all data written to the framebuffer.
-</para>
-</listitem>
 </itemizedlist>
 </para>
 </listitem>
@@ -98,11 +93,7 @@ Server structures.</para>
 <listitem>
 <para><filename class="directory">mi</filename> contains <glossterm
 linkend="gloss-mi-layer">machine independent</glossterm> drawing
-routines.  These drawing routines are used by the &project; Native GDI
-X Server engine.  In turn, the machine independent routines depend on
-<function>winGetSpans</function>, <function>winFillSpans</function>,
-and <function>winSetSpans</function>, which are implemented in the
-Native GDI engine.</para>
+routines.</para>
 </listitem>
 
 <listitem>
@@ -167,7 +158,8 @@ contains documentation for various components of the X Window System.
 </listitem>
 
 <listitem>
-<para>The various X Window System protocol headers.</para>
+<para><filename class="directory">xorgproto</filename>
+contains the various X Window System protocol headers.</para>
 </listitem>
 
 <listitem>