[gobject-introspection: 1/2] Convert README files to reST

[Christoph Reiter <creiter src gnome org>]

commit 3edf3ce62819e8ae11a2997c2489b408c4ff0ce9
Author: Christoph Reiter <reiter christoph gmail com>
Date:   Sat Jun 23 11:58:44 2018 +0200

    Convert README files to reST
    
    Rename the msvc readme file because otherwise gitlab picks it up as the default
    one for some reason.

 MSVC.README.rst      | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 Makefile.am          |  3 +-
 README.msvc          | 80 --------------------------------------------------
 README => README.rst | 27 ++++++++---------
 4 files changed, 96 insertions(+), 96 deletions(-)
---
diff --git a/MSVC.README.rst b/MSVC.README.rst
new file mode 100644
index 00000000..82000773
--- /dev/null
+++ b/MSVC.README.rst
@@ -0,0 +1,82 @@
+Building GObject-Introspection (G-I) on Windows using Visual Studio
+===================================================================
+
+Building G-I on Windows with Visual Studio is now supported via the use
+of the Meson build system, the Visual Studio 2008~2017 projects have been
+dropped from the distribution.  This README.msvc file will outline the
+steps of performing such a build on Visual Studio 2008~2017.
+
+You will need the following, in addition to your Visual Studio installation:
+
+- A Python installation that matches the build configuration that you are
+  planning to build.  That is, you need the 32-bit Python installation for
+  building 32-bit builds of G-I and the 64-bit (amd64) Python installation
+  for building x64/x86_64/amd64 builds of G-I.  You need at least the version
+  that is required for Meson, which is 3.4.x at the time of writing.  You will
+  then need to install Meson using the pip tool.
+
+- The Ninja build tool, which is optional on Visual Studio 2010, 2015 and 2017
+  builds (if one chooses to generate Visual Studio projects with Meson), but is
+  required for 2008, 2012 and 2013 builds.
+
+- GIT for Windows is recommended, as Meson will download using GIT the sources
+  of libraries that it depends on, if they cannot be found (such as GLib, please
+  see below)
+
+- A recent enough version of GLib, preferably built with the same compiler that
+  is now being used to build G-I.  If none is found, the Meson build will fetch
+  GLib from GIT master and build it first before continuing to build G-I.  Note
+  that it will require a libintl implementation (must be installed beforehand, the
+  headers and lib and DLL must be found in the paths specified by %INCLUDE, %LIB%
+  and %PATH% respectively), along with ZLib and libffi (GLib's own Meson build will
+  build  them if they are not found).  If a pre-existing copy of GLib is available,
+  be sure to set PKG_CONFIG_PATH to where its .pc files can be found, and ensure
+  that its DLLs/ executables can be first found in the paths specified in %PATH%.
+  Note that libffi is needed both by GLib and G-I.
+
+- A DLL build of Cairo with Cairo-GObject built, also preferably with the same
+  compiler that is now used to build G-I.
+
+- A recent version of winflex/flex and Bison. They can be obtained via MSYS/MSYS64
+  or Cygwin installations.  Either the 32-bit or 64-bit version will work, as long
+  as they run on your system.
+
+Set PATH to contain your Python-3.4.x+ interpreter, Ninja build tool (if needed) and
+winflex/flex and Bison executables towards its end.
+
+Note that if you plan to use g-ir-scanner for other packages built using Meson, you
+need to use the same Python release series (3.4, 3.5...) for running Meson there as
+well.
+
+Open a Visual Studio command prompt and create an empty build directory (which needs
+to be on the same drive as the G-I sources).  In that directory, run the following::
+
+  python $(PythonInstallationPath)\scripts\meson.py $(G-I_srcdir) --buildtype=<build_configuration> 
--prefix=$(PREFIX) -Dcairo-libname=<DLL filename of cairo-gobject>
+
+When Meson completes configuring and generating the build files, proceed building
+using Ninja or the generated Visual Studio projects.
+
+Additional notes for building with Visual Studio 2008 only
+----------------------------------------------------------
+Due to its use of security manifests, after Meson completes configuring and
+generating the build files, first build the giscanner\_giscanner.pyd target
+using 'ninja giscanner\_giscanner.pyd'.  After doing so, embed the manifest
+using the following command::
+
+  mt /manifest giscanner\_giscanner.pyd.manifest /outputresource:giscanner\_giscanner.pyd;2
+
+The .gir files cannot be successfully generated without this step.
+
+On x64 builds, building girepository\girepository-1.0-1.dll may hang during compilation.
+If this happens, terminate all 'cl.exe' processes, which will terminate the build process.
+Open build.ninja and change the compiler flags by changing /O2 to /O1 for all the sources
+that hang during compilation.  At this time of writing, girepository\girwriter.c,
+girepository\girparser.c and girepository\girnode.c are affected--this is due to an issue
+in Visual Studio 2008's x64 compiler in regards to optimization.  Re-attempt the build, and
+the build should complete normally.  This does not affect Win32/x86 builds.
+
+On all Visual Studio 2008 builds, after successfully completing/installing the build, run
+the following so that we ensure the manifests are embedded to the built DLLs and EXEs::
+
+  for /r %f in (*.dll.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f 
/outputresource:$(PREFIX)\bin\%~nf;2
+  for /r %f in (*.exe.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f 
/outputresource:$(PREFIX)\bin\%~nf;1
diff --git a/Makefile.am b/Makefile.am
index d941a3a9..e071ec25 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -58,7 +58,8 @@ EXTRA_DIST +=                         \
        misc/update-glib-annotations.py \
        misc/update-gtkdoc-tests.py     \
        misc/verbump.py         \
-       README.msvc \
+       README.rst \
+       MSVC.README.rst \
        meson.build \
        meson_options.txt
 
diff --git a/README b/README.rst
similarity index 92%
rename from README
rename to README.rst
index 4a57dc08..b8e82a9b 100644
--- a/README
+++ b/README.rst
@@ -4,8 +4,7 @@ The goal of the project is to describe the APIs and collect them in
 a uniform, machine readable format.
 
 GIR XML format
-==============
-
+--------------
 There's an XML format called GIR used by GObjectIntrospection.
 The purpose of it is to provide a common structure to access the complete
 available API that a library or other unit of code exports.
@@ -16,8 +15,7 @@ meant to be usable to use in other situations, for instance to/from another
 set of languages.
 
 Typelib
-=======
-
+-------
 The typelib is an on-disk version of the GIR designed to be fast, memory
 efficient and complete enough so that language bindings can be written
 on top of it without other sources of information.
@@ -26,9 +24,9 @@ accessed from the language binding or another application who wishes to
 use the information.
 
 Tools
-=====
-
+-----
 The following tools are shipped with GObject Introspection:
+
 - g-ir-scanner, a tool which generates GIR XML files by parsing headers,
   GTK-Doc comment blocks including annotations and introspecting GObject
   based libraries.
@@ -41,8 +39,7 @@ The following tools are shipped with GObject Introspection:
 - g-ir-doc-tool, generates API reference documentation from a GIR XML file.
 
 API library
-===========
-
+-----------
 There's also a C based library called libgirepository which provides
 an API to access to the typelib metadata. It also contains an API to
 invoke functions, given the function info object. The implementation is
@@ -53,18 +50,18 @@ There are a number of GIR test files in tests/, and a script to do
 roundtrip tests (GIR -> typelib -> GIR).
 
 Helping out
-===========
+-----------
 The introspection framework needs a lot more work, see TODO.
 
 Homepage
-========
-http://live.gnome.org/GObjectIntrospection
+--------
+https://gi.readthedocs.io/
 
 Reporting bugs
-==============
+--------------
 Bugs should be reported in https://gitlab.gnome.org/GNOME/gobject-introspection/issues.
 
 Contact
-=======
-Mail: gtk-devel-list gnome org
-IRC: #introspection irc gnome org
+-------
+:Mail: gtk-devel-list gnome org
+:IRC: #introspection irc gnome org
\ No newline at end of file