
  ULS INSTALLATION


  Quick Start - Linux
  ------------------
   On Debian platforms like Debian, Ubuntu, Mint, two deb-files is provided. 
      o uls_x.y.z_amd64.deb: for 64-bit mach(x86_64, amd64)
      o uls_x.y.z_i386.deb: for 32-bit mach
   To install the deb-file, download the proper file on the site(http://www.sourceforge.net/projects/uls).

   Enter the command as follows.
      sudo gdebi uls_x.y.z_amd64.deb

   To test the ULS, setup the examples of ULS by entering the command 'setup_uls_examples'.
      setup_uls_examples <dest-dir>
   There'll a directory called 'uls_examples' in the <dest-dir> after the command.

   To build the examples, do the followings
      $ make

   Test it:
      $ cd test_1st
      $ test_1st test_1st_sam.txt


  Building from the source code on Linux/macOS
  ------------------
     $ ./configure [--prefix=<INST_DIR>] [--with-etc-dir=<ADMIN_DIR>]
     $ make
     $ make check      
     $ sudo make install // install it using admin privilege.

  1) Replace <PREFIX> with the file path on which ULS is installed.
    Unless it's specified, <PREFIX> will be '/usr/local'.

  2) You can also change the admin-directory using the option of 'configure'
      For instance, if you want it to be '/opt/uls_1_8/etc',
           run 'configure' like this:
           ./configure --with-etc-dir='/opt/uls_1_8/etc'
      The default admin-directory is '/usr/local/etc/uls'.

  3) After installation, There'll be directories named 'bin', 'lib', include', and 'share'
       below the directory <PREFIX>.
    The 'bin' contains uls a few of utilities doing the following function.
       o ulc2class  : converts ulc-file into header file,
                   The generated file can be used in c, c++, java, or c#.

       o ulfgen     : gives users the statistic information on uses of keywords of language.
 
       o uls_stream : makes binary formatted stream file from input files.

       o uninstall_uls: will remove the package from your system.

    The 'include' contains the header files to compile your source file.
    The 'lib' contains the ULS libraries, 'libuls.*' and 'libulscpp.*'.
       o libuls : the core library of ULS.

       o libcompat : the code collection for wide-string, ANSI-encoding.
          This library wrap the libuls, so it calls the core api in 'libuls'.
          The wide-string API is available on both Linux and Windows.
          The ANSI-encoding API is available only on Windows.
 
       o libulscpp : the c++ wrapper for libuls.
 
       o UlsDotNet.dll : used in .NET for Windows C#.

    The 'share' contains sample ulc-files, such as java.ulc, sql.ulc python3.ulc, and man pages.

  4) To uninstall the package, run 'uninstall_uls' in the 'bin' directory:
     $ sudo uninstall_uls 


  Quick Start - Windows
  ---------------------
   How to install ULS-libraries into your system

   On Windows platforms,
     There is a self-extracting install program, uls-windows-{x64,i686}.exe 
         in the home-site(http://www.sourceforge.net/projects/uls).
     It contains the binaries which are targeted onto i386 and x86_64.
     Download and run it.

    After installation, the path for uls utilities should be appened to the environment variable 'PATH'.
    The value of 'PATH' is identified in 'Advanced' tab -- 'Environment Variables' -- 'User variables for...'
        in 'My Computer' -- 'Properties'.

    Try to run the followings commands to see the usages of uls-tools in dos-prompt.
       o Ulc2Class -h
       o UlsStream -h
       o UlfGen -h


  Source build - Windows
  ---------------------
   1) How to build it from sources
    The ULS-windows version is distributed with solution-files(*.sln) and 
       project-files(*.vcproj) in directory 'UlsWin'.

     a) After unpacking the source distribution (uls-x.y.z.tar.xz),
           run VisualStudio 2012(or later) by clicking UlsWin\UlsWin.sln.

     b) Either 'Release/Win32' or 'Release/x64' configuration 
           should be chosen according to your arch-type(32bit or 64bit).

     c) When the build-process is finished, all the executables and libraries will be located 
           in UlsWin\Release\{Win32,x64}.

   2) To build C++ examples,
     a) To see how the installed version works well, open 'UlsExamples.sln' in the UlsCpp\UlsExamples directory.
        To link the example programs with the Uls libraries and run executables,
          it's necessary to inform the linker of the location of the libraries.
        Check and modify the 'Additional Library Directories' in 'Configuration Properties' of each projects.
        By default, all the projects in the UlsCpp\UlsExamples will search 'C:\Program Files\UlsWin\lib' for the libraries.

     b) Choose the configuration Release/Win32 or Release/x64 according to your build system.

     c) The solution produces the executables, DumpToks.exe, Css3Toks.exe, 
           Html5Toks.exe, ShellToks.exe, MkfToks.exe, and TokSeq.exe in UlsCpp\UlsExamples\Release\{Win32,x64}.


  Demos - Windows
  ---------------------
   Now You can run the executables in the directory named 'UlsWin' in the desktop.
    Go to the directory 'Demos' in 'UlsWin'.
       o double-click the 'run_css3_demo.bat'.
       o double-click the 'run_html5_demo.bat'.
       o double-click the 'run_shell_demo.bat'.
       o double-click the 'run_mkf_demo.bat'.
       o double-click the 'run_tokseq_demo.bat'.


  For C# Users
  ---------------------
    The project UlsCs is a C# wrapper class library for UlsDotNet.dll and UlsCsHello is an example project to use it.
    To use the C# Uls library, the uls core library, UlsDotNet.dll, should be installed using 'setup.bat'.

     1) Getting the libraray files.
       a) To get the library UlsCs.dll from the source code, open the file 'UlsWin.sln' as
         the Uls C# library is contained in the solution.

       b) There's a project folder named 'UlsCsharp', 'UlsCs', and 'UlsCsHello' in it.

    Once the installationg complete, you can test the library with a basic C# program,
       the UlsCsHello.exe in 'UlsWin\UlsCsharp\UlsCsHello\bin\Release'.
       o UlsCsHello ..\..\input1.txt ..\..\sample1.ulc or
       o double-click the 'run_cs_hello_demo.bat'.

    After installing it with 'UlsWin\setup.bat', you can examine it using the projects
       in 'UlsWin\UlsCsharp\UlsCsExamples'.

    2) Building examples from source.
      To make the example executables from the source code,
         open the solution file 'UlsCsExamples.sln' in 'UlsCsharp\UlsCsExamples'.

       c) Be sure that there is no error in the library referencing to the UlsCs.dll in running UlsCsHello.
          Make sure that the external reference of 'UlsCs.dll' is correct in the property popup window.

       d) Choose the build configuration 'Release'--'Any CPU'.
           Build the solution!

    3) Test
      Entering each project folder 'Css3Toks', 'DumpToks', 'Html5Toks', and 'ShellToks',
       try running the project ouputs as follows
       o double-click the 'run_cs_css3_demo.bat'.
       o double-click the 'run_cs_dump_demo.bat'.
       o double-click the 'run_cs_html5_demo.bat'.
       o double-click the 'run_cs_shell_demo.bat'.


  For Java Developers
  ---------------------
    After installing Uls(linux/windows), launch the Elipse MARS or KEPLER (ver3.8.0 or later).
    Click the menu item 'Import...' in 'File'.
    Select 'General' -- 'Existing Projects into Workspace' and 'Next' button.
    Browse the source directory 'UlsJava' in 'Select root directory' and click 'Finish' button.

    If there's an error for 'JRE ... unbound', do the following steps.
       a) Right-button click of mouse on the 'UlsJava' solution in 'Project Explorer'
          and click 'Properties'.
       b) Choose the 'Java Build Path' and 'JRE System Library[...]' in the tab-menu 'Libraries'.
       c) Click the button 'Edit...' and select the JRE version installed in your system. 

    To run test the java programs,
       a) Right-button click of mouse on the 'UlsJava' solution in 'Project Explorer'
       b) Select 'Run As' -- 'Java Application'.
       c) 'UlsDump - uls.tests' should execute the following command.
          java uls.tests.UlsDump.class input1.txt
       d) 'UlsTestStream - uls.tests' should execute the following command.
          java uls.tests.UlsTestStream.class T="unsigned long long" tmpl_ex.uls

    To run test the java programs in terminal,
       in the directory 'UlsJava'
       a) java -cp ./bin;./libs/jna-3.5.2.jar uls.tests.UlsDump input1.txt
       b) java -cp ./bin;./libs/jna-3.5.2.jar uls.tests.UlsTestStream T="unsigned long long" tmpl_ex.uls
		or in Windows,
       c) java -cp uls_java.jar;jna-3.5.2.jar uls.tests.UlsDump input1.txt


 Uninstall
  ---------------------
    In order to uninstall ULS on Windows, go to the folder UlsWin in the desktop.
    Run the batch file named 'uninstall_uls.bat'.
    In Ubuntu, run the dpkg: dpkg -P uls


