Note: See also "BUILDING on Windows" in "../README".

This directory contains project files for building Link Grammar with the
Microsoft Visual Studio 2015 IDE (MSVC14). They were created and tested with
the Community Edition of that product.

Supported target versions
-------------------------
The intention is to support versions from Vista on (some WIN32
functions which are used are not supported in earlier versions.)

The system compatibility definitions:
In each project file - Target Platform version: 8.1
In the MSVC-common property sheet - C/C++->Preprocessor:
NTDDI_VERSION=NTDDI_VISTA;_WIN32_WINNT=_WIN32_WINNT_VISTA;

Dependencies
------------
The regex package, which includes libraries and header files, must be
separately downloaded. Also see GNUREGEX_DIR below.

Setup
-----
The build files make use of two User Macros, defined in the property
sheet "Local" - GNUREGEX_DIR and (optionally) JAVA_HOME, as follows:

-- GNUREGEX_DIR must be pointing to an unzipped POSIX regex distribution
   (which has the subdirectories "include" and "lib"). Its default is
   "%HOMEDRIVE%%HOMEPATH%\Libraries\gnuregex".
   If the environment variable GNUREGEX exists, its value is used instead.
   The library file name is assumed to be "regex.lib" and needs to be
   generated from the DLL if it is not included in the distribution (see
   http://stackoverflow.com/questions/9946322).

-- JAVA_HOME, if used, must be pointing to a locally installed SDK/JDK,
   which has the subdirectories "include" and "include/win32" (defined in
   the LinkGrammarJava project under Common properties->C/C++->General->
   Additional Include Directories.
   If your JAVA SDK/JDK installation has defined the JAVA_HOME environment
   variable (check it) then there is no need to define this User Macro.

Compiling
---------
- Compiling and running got checked on Windows 10, but is intended to be
  compatible to Vista and on (XP is not supported).

- To compile LinkGrammar, open the solution file LinkGrammar.sln, change
  the solution platform to x64 if desired, and build.

- The solution configuration is configured to create a debug version by
  default.  It's probably a good idea to switch a "Release" configuration.
  You can do this at Build Menu->Configuration Manager.

- The wordgraph-display feature is enabled when compiled with
  USE_WORDGRAPH_DISPLAY (already defined in the LGfeatures property sheet
  Common properties->C/C++->Preprocessor/Preprocessor Definitions).

- By default, the library is configured to create a DLL. If you want
  to instead build a static library, the macro LINK_GRAMMAR_STATIC must
  be defined before the inclusion of any header files for both the compiling
  of the link-grammar library and for the application that uses it. Other
  compiler settings will also have to be changed to create a static library
  of course.

Running
-------
The last step of the "LinkGrammarExe" project creates "link-parser.bat".  Copy
it to somewhere in your PATH and then customize it if needed (don't customize
it in-place, since rebuilding would overwrite it). Especially, add to PATH the
directory in which the regex DLL resides (see the line containing "DLLs"). If
you would like to display the wordgraph (see below) set also the PATH for
"dot.exe" if it is not already in your PATH.

If USE_WORDGRAPH_DISPLAY has been used when compiling (the default), then
typing !test=wg at the "link-parser" prompt can be used in order to display the
wordgraph of the next sentences to be parsed. See "../linkgrammar/README" for
how to use optional display flags.  By default, "PhotoViewer.dll" is invoked to
display the graph.  If X11 is available and your "dot.exe" command has the
"xlib" driver, it can be used to display the wordgraph when the x flag is set
(i.e.  !test=wg:x), for example when running under Cygwin/X. In any case it
uses the "dot" command of Graphviz. Graphviz can be installed as part of Cygwin
(in which case it included the "xlib" driver"), or separately
(http://www.graphviz.org/Download_windows.php).  Both "PhotoViewer.dll" (if
used) and "dot" must be in your PATH (if needed, you can customized that in a
copy of "link-parser.bat", as described above).

BTW, when running and MSVC-compiled binary under Cygwin, don't exit
link-parser by using ^Z - the shell may get stuck because the program
somehow may continue to run in the background.  Instead, exit using !exit .

NOTE: The created DLLs need the MSVC14 runtime environment to run. This is
normally already installed in your machine with the installation of the IDE.
But to be able to run Link Grammar on other computer you need to install the
Visual C++ Redistributable for Visual Studio 2015 from:
https://www.microsoft.com/en-us/download/details.aspx?id=48145
This redistributable does not contain debug version of the MSVC runtime, so
only "Release" Link Grammar will work with it.

Locale settings
---------------
In this version, the language dictionaries under the data directory define
the locale that they need in order to process input sentences and the
library automatically uses this locale, in a manner that is intended to be
compatible with creating several different dictionaries per thread.

If you use a dictionary which doesn't have this definition, or would like
to set the default language when link-parser is invoked without a language
argument, you can set the locale using the environment variable LANG,
using a 2-letter language code and a 2-letter country code:

> set LANG=ll-CC
For example:
> set LANG=en-US

If you open a dictionary which doesn't have a locale definition, from a
program (C program or a language with LG bindings) you have to set the
correct locale (for the whole program or the particular thread)for the
dictionary before creating the dictionary.  Alternatively, the LANG
environment variable can be set before creating the dictionary.

The code page of the console should not be changed, unless it is desired
to pipe the output to another program. In that case, this other program
may read garbage due to a limitation in the way cmd.exe implements pipes.
This can be solved as following ("more" is the example program)

link-parser | (chcp 65001 & more)

In that case "more" will be able to read UTF-8 input. However, the
display may still not be perfect due to additional cmd.exe limitations.

Console fonts
-------------
Courier New may be appropriate for all the languages in the data
directory. If you don't have it in the console menu, it can be added
through the registry (Google it).

Implementation notes:
---------------------

- The file "link-grammar/link-features.h.in" has a Custom Build Tool definition
  which invokes "mk-link-features-h" to generate
  "link-grammar/link-features.h", with LINK_*_VERSION variable replacement as
  defined in "configure.ac".

- The project file "LinkGrammarExe" has a Post-Build-Event definition for
  generating "link-parser.bat".


Using a remote network share
----------------------------
In order to use a link-grammar source repository from a network share (e.g. via
Samba), and still be able to use the custom build steps in the Project files,
there is a need to "convince" Windows it is a local filesystem.  Else you will
get "UNC path are not supported." on the batch runs, with bad results. This
method will also allow the "link-parser.bat" file to run.  (For other solutions
see tackoverflow.com/questions/9013941). You will need to find out by yourself
if this makes a security or another problem in your case.

Here is what worked for me:
Suppose you use host:/usr/local/src remotely as share "src":

mklink /J src-j \\host\src
mklink /D src src-link

The second one needs administrator privileges.
Then use the repository through "src".
