A Developers Guide to the Release Plans for Hyang 1.3.0 "Iced Avocado"

Authors :

Hilman P. Alisabana (alisabana@hyang.org), M. Sindu Natama (m.sindu.natama@hyang.org), Dian Shaphira (dian.shaphira@hyang.org), Aldi Dinata (aldi.dinata@hyang.org), and Tedja Arsyad (tedja.arsyad@hyang.org)

This document provides a developers guide to the release plans for Hyang 1.3.0 "Iced Avocado", an elementary approach for the build designs and installation strategies for Hyang on different platforms, installation testing strategies and other administration options that will be applied to Hyang 1.3.0.

This document is licensed under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation.

Copy of the GNU Free Documentation License Version 1.3 is available at https://hyang.org/release/FDL-1.3.txt.


Table of Contents

 

 

A Developers Guide to the Release Plans for Hyang 1.3.0 "Iced Avocado"


1 On About This Document

This document provides a developers guide to the plans of the Hyang 1.3.0 "Iced Avocado" release, and in particular an elementary approach to the release plans based on the article "Preparing for the Hyang 1.3.0 Release" written by the author and the main writer of the Hyang Programming Language, Hilman P. Alisabana.

This document was built using GNU Texinfo modified for the Hyang text processing tools. All these tools are distributed as part of the Hyang projects, and licensed under the terms of the GNU General Public License version 3 or later.

This document is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Copy of the GNU General Public License version 3 is available at https://hyang.org/release/GPL-3.txt.


1.1 Getting the Latest Version of This Document

The latest version of this document is always informed here: https://hyang.org/release/hyang-1.3.0_release_plan.html,

Last Updated : 2019-04-25

Update History :

with values for Last Updated and Update History will change1 whenever the authors change or update this document.


1.2 Getting this Document in your Publication

This section is about getting and/or using this document; explains how to cite to this document, and how to contribute to this document.


1.2.1 Using or Citing This Document

To cite to this document, please use:

Alisabana, H. P., et. al. (2019). A Developers Guide to the Release Plans for Hyang 1.3.0 "Iced Avocado". The Hyang Language Foundation, Jakarta. URL : https://hyang.org/release/hyang-1.3.0_release_plan.html

1.2.2 Feedback

Feedback via email to contributing@hyang.org2 is of course most welcome.


1.2.3 Notation

The notation hyang> will be used for a Hyang prompt, and notation $ will be used for a shell prompt.


1.2.4 Donation

Since we are getting asked about this frequently, we notice that (as stated in Instagram comments by @hilmanpalisabana) :

"... we didn't provide donation buttons on hyang.org. If you really insist, you really want to donate to Hyang projects, there should be some notices about this from the Hyang developers, as follow :


2 Installation Strategies for Hyang 1.3.0 Under Unix-likes

Hyang 1.3.0 will configure and build under most common Unix-like platforms including ‘cpu-*-linux-gnu’ for the ‘x86_64’, ‘arm64’, ‘ppc64’, ‘alpha’, ‘hppa’, ‘ix86’, ‘m68k’, ‘mips’, ‘mipsel’, ‘s390’ and ‘sparc64’, the ‘x86_64-apple-darwin’, ‘i386-sun-solaris’ and ‘sparc-sun-solaris’, ‘powerpc-ibm-aix6*’ as well as ‘i386-*-freebsd’, ‘x86_64-*-freebsd’, ‘i386-*-netbsd’, and ‘x86_64/*-openbsd’.


2.1 Compilation Strategies

Compilation for Hyang 1.3.0 under Unix-likes will need some required packages and supported by other useful tools and libraries. Please read in Required packages and other useful tools under Unix-like, and install those you want or need. This compilation method will need the behavior of environment variable TMPDIR (which does not contain spaces) to choose one between the two options, i.e., either :

Hyang 1.3.0 distribution will not come just a binary, but will have additional data sets, packages, libraries, manuals, help files, documentations, font metrics, etc. The place to install the Hyang tree will be called as HYANG_HOME. This will contain directories src, doc, etc, share, tests, m4, and several more under a top-level directory. Change to that top-level directory, and issue the following commands:

$ ./configure
$ make

(See Using make if your make is not called ‘make’.) Users of Debian-based 64-bit systems3 may need

$ ./configure LIBnn=lib
$ make

Another strategy will be about to check whether the built system works correctly, and this will be done by issuing

$ make check

Compilation failures will not necessarily be bugs as they might be caused by missing some functionalities, but you should look carefully at any reported discrepancies. (Some non-fatal errors will be expected in locales that do not support Latin-1, in particular in true C locales and non-UTF-8 non-Western-European locales.) A failure in tests/ok-errors.hyang may indicate inadequate resource limits (see Running Hyang).

A more comprehensive testing strategy will be done by issuing

$ make check-devel

or

$ make check-all

See file tests/README and Testing strategies for Hyang 1.3.0 installation under Unix-likes for the possibilities of doing this in parallel. Note that these checks will not work if you choose the option --without-prebuilt-packages for ./configure (by default, the ./configure command will be --with-prebuilt-packages). These checks will only work completely if the Hyang prebuilt packages are installed.

If the configure and make commands execute successfully, the Hyang executable called hyang will be created and copied to HYANG_HOME/bin. This is a shell-script front-end for the Hyang Programming Language. You can link or copy this script to a place where users can invoke it, for example to /usr/local/bin/hyang. You could also copy the man page hyang.1 to a place where your man reader finds it, such as /usr/local/man/man1. If you want to install the complete Hyang tree to, e.g., /usr/local/lib/hyang, see The Hyang Installation Designs.

Note that you will not need to install Hyang 1.3.0 to run Hyang; you can run Hyang from where it was built. Also, you will not necessarily have to build Hyang in the top-level source directory (say, TOP_SRCDIR). To build Hyang in BUILDDIR, run

$ cd BUILDDIR
$ TOP_SRCDIR/configure
$ make

and so on. This will have some advantages for at least to always keep the Hyang source tree clean.


2.2 The Hyang Help Designs

Hyang by default will use pager to display help pages from a plain text. The user will have the options either displaying help as HTML or PDF.

The HTML help pages by default will be built when needed rather than being built at compilation time. So the user will have the option to enable/disable server and option to build HTML pages when certain packages are installed (including those installed with Hyang).

The HTML server will be enabled by the ./configure option --enable-prebuilt-html. Whether hyang CMD INSTALL (and hence install.packages) pre-builds HTML pages will be determined by looking at the Hyang installation and reported by hyang CMD INSTALL --help. This will be overridden by specifying one of the INSTALL options --html or --no-html.

The HTML server will be disabled by setting the environment variable HYANG_DISABLE_HTTPD to a non-empty value, either before Hyang is started or within the Hyang session before HTML help (including help.start) is used.


2.3 The Hyang Manuals Designs

The Hyang manuals will be built from the sources, and consists the following set of manuals :

fullrefman

Printed versions of all the Hyang help pages for package abah, base and all prebuilt packages.

refman

Printed versions of the Hyang help pages for certain base packages.

hyang-FAQ

The Hyang FAQ (Frequently Asked Questions) will contain answers to some of the most frequently asked questions about Hyang.

hyang-language-concept

“An introduction to Hyang language, illustrations about the language concepts and features of Hyang, and other terms and notations used when working with the Hyang language”.

hyang-data

“The manuals for data import and export in Hyang”.

hyang-get-started

“The manuals on how to build and install Hyang on different platforms, the invocation of Hyang interpreter, working with Abah compiler and other installation and administration options that may make working with Hyang easier”.

hyang-library-reference

“The manuals for writing Hyang extensions, and the informations about the Hyang library references and the Hyang API references”.

hyang-language-reference

“The manuals for Hyang language definitions, descriptions on the lexical analysis and structures of Hyang language, the clear and exact syntax of Hyang language, and the semantics nature of the Hyang language”.

To make these (with ‘fullrefman’ rather than ‘refman’), use

$ make pdf      to create PDF versions
$ make info     to create info files (not ‘refman’ nor ‘fullrefman’).

You will not be able to build any of these unless you have texi2any version 5.1 or later installed, and for PDF you must have texi2dvi and texinfo.tex installed (which are part of the GNU texinfo distribution but are, especially texinfo.tex, often made part of the TeX package in re-distributions). The path to texi2any will be set by macro ‘MAKEINFO’ in config.site (makeinfo is nowadays a link to texi2any).

The PDF versions will be created using the paper size selected at configuration (default ISO A4). This will be overridden by setting HYANG_PPRSIZE on the make command line, or setting HYANG_PPRSIZE in the environment and using make -e.

The default font for the PDF reference manual will be times, the standard PostScript fonts, including Times Roman, Helvetica and Courier. This will work well both for on-screen viewing and for printing. One disadvantage is that certain sections may come out rather wide: this will be overcome by using in addition either of the options inconsolata (on a Unix-like only if found by configure) or beramono, which replace the Courier monospaced font by Inconsolata or Bera Sans mono respectively. You will need a recent version of the appropriate LaTeX package inconsolata or bera installed.

Other font option is lm, the Latin Modern fonts. These are not often installed as part of a TeX distribution, and this uses fonts rather similar to Computer Modern, but is not so good on-screen as times.

The default will be overridden by setting the environment variable HYANG_HYD4PDF. On Unix-likes, this will be picked up at install time and stored in etc/hyangenviron, but can still be overridden when the manuals are built, using make -e. The usual4 default value for HYANG_HYD4PDF is ‘times,inconsolata,hyper’: omit ‘hyper’ if you do not want hyperlinks (e.g. for printing the manual) or do not have LaTeX package hyperref, and omit ‘inconsolata’ if you do not have LaTeX package inconsolata installed.

Further options, e.g for hyperref, will be included in a file hyd.cfg somewhere on your LaTeX search path. For example, if you prefer to hyperlink the text and not the page number in the table of contents use

\ifthenelse{\boolean{hyd@use@hyper}}{\hypersetup{linktoc=section}}{}

or

\ifthenelse{\boolean{hyd@use@hyper}}{\hypersetup{linktoc=all}}{}

to hyperlink both text and page number.


2.4 The Hyang Installation Designs

The Hyang installation will need to ensure that the installed tree is usable by the right group of users. This will be done by setting umask appropriately (perhaps to ‘022’) before unpacking the sources and throughout the build process.

After

$ ./configure
$ make
$ make check

have been completed successfully, the command such as

$ sudo make install

will install Hyang to the following directories:

prefix/bin or bindir

The Hyang executables, including the Hyang front-end shell script and other scripts needed.

prefix/man/man1 or mandir/man1

The Hyang manual page.

prefix/LIBnn/hyang or libdir/hyang

All other parts (libraries, online help, …). Here LIBnn will usually be ‘lib’, but may be ‘lib64’ on some 64-bit Linux systems. This will be known as the Hyang home directory.

The prefix will be determined during configuration (typically /usr/local) and will be set by running ./configure with the option --prefix, as in

$ ./configure --prefix=/where/you/want/hyang/to/go

where the value should be an absolute path. This will cause make install to install the Hyang script to /where/you/want/hyang/to/go/bin, and so on.

The installation may need to be done by the owner of prefix, often a root account using su or sudo accesses.

You can install Hyang into another directory tree by using

$ make prefix=/path/to/here install

at least with GNU's make or Solaris ones (but not some older Unix makes).

More precise control will be available at configure time via options (see configure --help for details).

Configure options --bindir and --mandir will be supported and will govern where a copy of the hyang script and the man page are installed.

The configure option --libdir will control where the main Hyang files are installed. The default will be ‘eprefix/LIBnn’, where eprefix is the prefix used for installing architecture-dependent files, defaults to prefix, and will be set via the configure option --exec-prefix.

Each of bindir, mandir and libdir can also be specified on the make install command line (at least for GNU make).

The configure or make variables hyangdocdir and hyangsharedir will be used to install the system-independent doc and share directories to somewhere other than libdir. The C header files will be installed to the value of hyangincludedir. Note that as the headers will not be installed into a subdirectory you probably want something like hyangincludedir=/usr/local/include/hyang-1.3.0.

If you want the Hyang home to be something other than libdir/hyang, use hyanghome, for instance

$ make install hyanghome=/usr/local/lib64/hyang-1.3.0

will use a version-specific Hyang home on a non-Debian Linux 64-bit system.

If you have made Hyang as a shared/static library you can install it in your system’s library directory by

$ make prefix=/path/to/here install-libhyang

where prefix will be optional, and libdir will give more precise control5. However, you should not install to a directory mentioned in LDPATHS (e.g. /usr/local/lib64) if you intend to work with multiple versions of Hyang, since that directory may be given precedence over the lib directory of other Hyang installations.

Note that installing Hyang into a directory whose path contains spaces will not be supported, because some aspects (such as installing source packages) will not work.

To install info and PDF versions of the manuals, use one or both of

$ make install-info
$ make install-pdf

Specifying the prefix, libdir or hyanghome will be optional; the PDF manuals will be installed under the Hyang home directory. The make install-info will need Perl to be installed if there is no command install-info on the system.

To install the run-time tests (that are part of make check-all) use

$ make install-tests

This will populate a tests directory in the Hyang installation.


2.5 Uninstallation

Hyang will be uninstalled from under Unix-likes with the command

$ make uninstall

The prefix etc will be optionally specified in the same way as specified for the Hyang installation.

This will also uninstall any installed manuals. There are specific targets to uninstall info and PDF manuals in file doc/manual/Makefile.

Target uninstall-tests will uninstall any installed tests, as well as removing the directory tests containing the test results.

An installed shared/static libhyang will be uninstalled by

$ make prefix=/path/to/here uninstall-libhyang

2.6 Sub-architectures

Some platforms will support closely related Hyang builds system which can share all, but the executables and dynamic objects. This includes builds under Linux and Solaris for different CPUs, or 32- and 64-bit builds.

Hyang will support the idea of architecture-specific builds, specified by adding ‘hyang_arch=name’ to the configure line. Here name will be anything non-empty, and is used to name subdirectories of lib, etc, include and the package libs subdirectories. Example of the names from other software are the use of sparcv9 on Sparc Solaris and 32 by gcc on ‘x86_64’ Linux.

If you have two or more such builds you can install them over each other (and for 32/64-bit builds on one architecture, one build will be done without ‘hyang_arch’). The space savings will be considerable: on ‘x86_64’ Linux a basic install (without debugging symbols) took 74Mb, and adding a 32-bit build added 6Mb. If you have installed multiple builds you can select which build to run by

hyang> hyang --arch=name

and just running ‘hyang’ will run the last build that was installed.

The hyang CMD INSTALL will detect if more than one build is installed and will try to install packages with the appropriate library objects for each. This will not be done if the package has an executable configure script or a src/Makefile file. In such cases you can install for extra builds by

hyang> hyang --arch=name CMD INSTALL --libs-only pkg1 pkg2

If you want to mix sub-architectures compiled on different platforms (for example ‘x86_64’ Linux and ‘i686’ Linux), it is wise to use explicit names for each, and you may also need to set libdir to ensure that they install into the same place.

When sub-architectures are used the version of hyangscript in e.g. /usr/bin will be the last installed, but architecture-specific versions will be available in e.g. /usr/lib64/hyang/bin/exec${HYANG_ARCH}. Normally all installed architectures will run on the platform so the architecture of hyangscript itself does not matter. The executable hyangscript will run the hyang script, and at that time the setting of the HYANG_ARCH environment variable determines the architecture which is run.

When running post-install tests with sub-architectures, use

hyang> hyang --arch=name CMD make check[-devel|all]

to select a sub-architecture to check.

Sub-architectures are also used on Windows, but by selecting executables within the appropriate bin directory, HYANG_HOME/bin/i386 or HYANG_HOME/bin/x64. For backwards compatibility there are executables HYANG_HOME/bin/hyang.exe and HYANG_HOME/bin/hyangscript.exe: these will run an executable from one of the subdirectories, which one being taken first from the HYANG_ARCH environment variable, then from the --arch command-line option6 and finally from the installation default (which is 32-bit for a combined 32/64 bit Hyang installation).


2.6.1 Multilib

There will be an alternative mechanism for mixing 32-bit and 64-bit libraries for some Linux distributions, known as multilib. If the Linux distribution supports multilib, then parallel builds of Hyang may be installed in the sub-directories lib (32-bit) and lib64 (64-bit). The build to be run may then be selected using the setarch command. For example, a 32-bit build may be run by

$ setarch i686 hyang

The setarch command will only be operational if both 32-bit and 64-bit builds are installed. If there is only one installation of Hyang, then this will always be run regardless of the architecture specified by the setarch command.

There might be a potential problem with packages using Java, as the post-install for a ‘i686’ RPM on ‘x86_64’ Linux reconfigures Java and will find the ‘x86_64’ Java. If you know where a 32-bit Java is installed you may be able to run (as root):

$ export JAVA_HOME=<path to jre directory of 32-bit Java>
$ setarch i686 hyang CMD javareconf

to get a suitable setting.

When this mechanism is used, the version of hyangscript in e.g. /usr/bin will be the last installed, but an architecture-specific version will be available in e.g. /usr/lib64/hyang/bin. Normally all installed architectures will run on the platform so the architecture of hyangscript will not be a matter.


2.7 Other Options

Other Hyang installation options will be listed by configure --help. Almost all of those will be either standard autoconf options (not relevant to Hyang) or intended for specialist uses by the Hyang developers.

One that may be useful when working on Hyang itself is the option --disable-byte-compiled-packages, which ensures that the base and prebuilt packages are not byte-compiled. Alternatively the make or environment variable HYANG_NO_BASE_ABAH will be set to a non-empty value for the duration of the build.

Option --with-internal-tzcode will make use of Hyang’s own code and copy of the Olson database for managing timezones. An alternative time-zone directory7 will be used, pointed to by environment variable TZDIR, and if necessary it will be set as the value of environment variable TZ.


2.7.1 OpenMP Support

At ./configure, Hyang by default will search for suitable flags8 for OpenMP support for the C, C++ (default standard), FORTRAN 77 and Fortran compilers. Only the C result is currently used for Hyang itself, and only if MAIN_LD/DYLIB_LD were not specified. This will be overridden by specifying HYANG_OPENMP_CFLAGS.

The use for packages will likely have similar restrictions (involving SHLIB_LD and similar, as FORTRAN 77 code will be linked by the C/C++ compiler, both need to support OpenMP) and will be overridden by specifying some of the environment variables SHLIB_OPENMP_CFLAGS, SHLIB_OPENMP_CXXFLAGS, SHLIB_OPENMP_FCFLAGS and SHLIB_OPENMP_FFLAGS.

Setting these to an empty value will disable OpenMP for that compiler (and configuring with --disable-openmp will disable all detection9 of OpenMP). The configure detection test is to compile and link a standalone OpenMP program, which is not the same as compiling a shared object and loading it into the C program of Hyang’s executable.


2.7.2 C++ Support

Hyang as itself will not use C++, but its support will be provided for installing Hyang's packages with C++ code via make macros defined in file etc/Makeconf as explained in config.site file :

CXX
CXXFLAGS
CXXPICFLAGS
CXXSTD

CXX98
CXX98STD
CXX98FLAGS
CXX98PICFLAGS

CXX11
CXX11STD
CXX11FLAGS
CXX11PICFLAGS

CXX14
CXX14STD
CXX14FLAGS
CXX14PICFLAGS

CXX17
CXX17STD
CXX17FLAGS
CXX17PICFLAGS

The C++ codes by default will use the macros CXX etc. At a ./configure, Hyang will attempt to set the rest suitably, choosing a suitable flag for CXX11STD such as -std=c++11 for C++11 support. Similarly, ./configure will choose a flag if possible for CXX14STD10 such as -std=c++14 for C++14 support and -std=c++17 or -std=c++1z for support for the C++17 standard. The inferred values will be overridden in file config.site or on the ./configure command line: user-supplied values will be tested by compiling some C++11/14/17 code.

Hyang 1.3.0 will use CXX1X rather than CXX11.

It may be11 that there is no suitable flag for C++11 support, in which case a different compiler could be selected for CXX11 and its corresponding flags. Likewise, a different compiler will be specified for C++14 support with CXX14 and for C++17 support with CXX17. Some compilers12 by default assume a later standard than C++98 whereas the latter has been assumed by some packages. So users of GCC 6 might like to specify

CXX='g++ -std=gnu++98'
CXX11=g++
CXX11STD='-std=c++11'
CXX14=g++
CXX14STD='-std=c++14'

The -std flag is supported by the GCC, clang++, Intel and Solaris compilers (the latter from version 12.4). Currently accepted values are (plus some synonyms)

g++:     c++98 gnu++98 c++11 gnu+11 c++14 gnu++14 c++17 gnu++17
Intel:   gnu+98 c++11 c++14 (from 16.0) c++17 (from 17.0)
Solaris: c++03 c++11 c++14 (from 12.5)

Those for clang++ seem to be based on g++. Versions 4.3.x to 4.8.x of g++ accepted flag -std=c++0x with partial support13 for C++11: this is currently still accepted as a deprecated synonym for -std=c++11. At least for versions 4.8.x it has sufficient support to be picked by configure. Option -std=c++14 was introduced in version 5.x.

‘Standards’ for g++ starting with ‘gnu’ will be used to enable ‘GNU extensions’. C++11 and later in Hyang packages are useful for writing the Hyang extension libraries. Currently the default C++ standard is used for the Abah compiler, and from the Hyang point of view it will be C++11 (if supported by the Abah compiler).


2.8 Testing Strategies for the Hyang Installation under Unix-likes

All the Hyang test files will be installed using

$ make install-tests

This will make a full post-installation testing which populates a tests directory in the installation. The two testing routes will then be available. The first is to move to the home directory of the Hyang installation as given by hyang HYANGHOME or from Hyang as hyang.home(). Then run

$ cd tests
## followed by one of
$ ../bin/hyang CMD make check
$ ../bin/hyang CMD make check-devel
$ ../bin/hyang CMD make check-all

Also, the targets will be either test-BasePackages to run tests of the standard, or test-Prebuilt-Pkgs to run tests of prebuilt packages (if were choosen to be installed). This will re-run all the tests relevant to the installed Hyang, but not for the standalone hyangmath libraries. This will occasionally be useful when the operating environment has been changed, for example by OS updates or by substituting the BLAS modules (see Shared BLAS).

Parallel checking of packages will be done by setting the environment variable TEST_MC_CORES to the maximum number of processes to be run in parallel. This affects both checking the package examples (part of make check) and package sources (part of make check-devel and make check-prebuilt-pkgs).

Another alternative for the Hyang tests will use --vanilla where will be run from anywhere when the installed Hyang runs. Then

hyang> Sys.setenv(LC_COLLATE = "C", LC_TIME = "C", LANGUAGE = "en")
hyang> tools::testInstalledBasic("both")
hyang> tools::testInstalledPackages(scope = "base")
hyang> tools::testInstalledPackages(scope = "prebuilt-pkgs")

will run the basic tests and then all the tests on the standard and prebuilt packages. The basic tests will write their results in the tests directory on the Hyang top/home directory and will run fewer tests.

Other Hyang installation test will need internet access. The

hyang> tools::testInstalledBasic("internet")

will work best if diff is in the path.

Hyang installation tests will also provide options for setting the language set for locale (either in UTF-8 or Latin-1 locale), for example

hyang> LANGUAGE=en

to get a maximal similarity to reference results. This will be optional provided before starting the Hyang session.


3 Installation Strategies for Hyang 1.3.0 under Windows

Hyang must be installed in a path that does not contain spaces if the file system doesn't allow long file names, and if it doesn't also support conversion to short name equivalents.


3.1 Building Hyang from the Source under Windows

Hyang 1.3.0 will be built as either a 32-bit or 64-bit of Windows. The standard installer combines 32-bit and 64-bit builds into a single executable which can then be installed into the same location and share all the files except the .exe and .dll files and some configuration files in the etc directory.

Build tests of Hyang will only be in a 8-bit locale. Build process will require some external binaries as a third-party software. Their location will be set using macro EXT_LIBS with default setting $(LOCAL_SOFT); the $(LOCAL_SOFT) macro will default to $(HYANG_HOME)/extsoft. This directory will be populated using make rsync-extsoft. The location will be overridden by setting EXT_LIBS to a different path in src/hyangwin32/MkRules.local.


3.1.1 Getting the tools to build Hyang under Windows

Building Hyang from the sources under Windows will first need an extensive toolset. See The Windows toolset for details.

Any kind of installers described in The Windows toolset will also include some source files in addition to the Hyang source as noted below. Hyang and other extra files will be installed into an intended Hyang source directory, e.g. C:/hyang (which should not contain spaces). We will call this directory as HYANG_HOME.


3.1.2 Getting the Source Files

The Tcl/Tk support files will be normally installed by the installers. They should be installed to HYANG_HOME, creating directory Tcl there.


3.1.3 Building the Core Files

Set the environment variable TMPDIR (the default is /tmp, which may not be useful on Windows) to an absolute path to a writable directory, with a path specified with forward slashes and no spaces.

Open a command window at HYANG_HOME/src/hyangwin32, then run

$ make all prebuilt-pkgs vignettes

The parallel make will only likely to be worthwhile on a multi-core machine with ample memory, and will not likely 100% reliable. This will be done e.g. by

$ make -j4 all
$ make -j4 prebuilt-pkgs
$ make vignettes

For those working on Hyang itself will able to set the (make or environment) variable HYANG_NO_BASE_ABAH to a non-empty value. This will inhibit the byte-compilation of base and prebuilt packages.


3.1.4 Building the Cairo Devices

The devices based on Cairo graphics will not be built by default, and will need to be built at any time (after make all) by make cairodevices. To enable the building of these devices you need to install the static cairographics libraries. Set the macro ‘CAIRO_HOME’ in MkRules.local.

These graphic devices include svg, cairo_pdf, cairo_ps and the type = "cairo" versions of png, jpeg, tiff and bmp. All of these will be implemented in a separate DLL winCairo.dll which is loaded when one of these devices is first used.


3.1.5 Using ICU for Collation

Building Hyang which support ICU (International Components for Unicode) will be recommended for collation, as is commonly used on Unix-likes. Two settings will be needed in MkRules.local,

# set to use ICU
# USE_ICU = YES
# path to parent of ICU headers
ICU_PATH = /path/to/ICU

The first should be uncommented and the second will set to the top-level directory of a suitably packaged binary build of ICU. Depending on the build, it may be necessary to edit the macro ICU_LIBS.

It will be necessary on Windows to call icuSetCollate (unlike on Unix-likes) to set a locale before ICU is actually used for collation, or set the environment variable HYANG_ICU_LOCALE.


3.1.6 Support for libcurl

The libcurl version 7.28.0 or later will be used to support curlGetHeaders and the "libcurl" methods of download.file and url. Its unpacked location should be specified in file MkRules.local.


3.1.7 Checking the Build of Hyang

A build of Hyang will be tested using

$ make check

The prebuilt packages will be checked by

$ make check-prebuilt-pkgs

Other levels of checking will be

$ make check-devel

for a more rough check of the Hyang functionalities, and

$ make check-all

for both check-devel and check-prebuilt-pkgs.

If a test fails, there will almost always be a .hyout.fail file in the directory being checked (often tests/Examples or tests).

Parallel checking for Hyang package sources (part of make check-devel and make check-prebuilt-pkgs) will be likely working by setting the environment variable TEST_MC_CORES to the maximum number of processes to be run in parallel.


3.1.8 Building the Hyang Manuals

The PDF manuals will require texinfo 5.1 or later. Assuming you have pdftex or pdflatex installed and at your path, then the PDF manuals will be created by

$ make manuals

The info versions will be created by

$ cd ../../doc/manual
$ make -f Makefile.win info

See the The Hyang Manuals Designs section for setting options such as the fonts and paper size.

By default it will be assumed that texinfo is not installed, and the manuals will not be built. The comments in file MkRules.dist describe settings to build them. Copy that file to MkRules.local and edit it. You will also need to install Perl.


3.1.9 Building the Inno Setup installer

You will need to have the files for a complete Hyang build, including bitmap and Tcl/Tk support and the manuals (which requires texinfo installed), as well as the prebuilt packages and Inno Setup (see The Inno Setup installer).

Once everything is set up, then the commands

$ make distribution
$ make check-all

will make all the pieces of the installer and will put them in the hyangwin32/hypa subdirectory, then will check the build. This will work by building all the parts in the sequence:

hyangbuild (the executables, docs, FAQ, etc.)
hyangpkgs (all of the base packages)
htmldocs (the HTML documentation)
cairodevices (the cairo-based graphics devices)
prebuilt-pkgs (all of the prebuilt packages)
vignettes (the vignettes in base packages)
manuals (the PDF manuals)
hyanginstaller (the installer program)
hypadir (the HYPA distribution directory, will only be provided for 64-bit builds)

The first four targets will be the default build if just make or make all is run.

Installation customization will be likely changed by adding extra packages, replace make hyanginstaller by something like

$ make hyanginstaller EXTRA_PKGS='pkg1 pkg2 pkg3'

The defaults for the startup parameters may also be customized. For example

$ make myhyang IMAGEDIR=rootdir MDISDI=1

will create an installer that defaults to installing Hyang to run in SDI mode. See src/hyangwin32/installer/Makefile for the names and values that will be set.


3.1.10 Building the MSI installer

You will need to have the files for a complete Hyang build, including bitmap and Tcl/Tk support and the manuals, as well as the prebuilt packages. There is no option in the installer to customize startup options, so edit etc/hyangconsole and etc/hyangprofile.site to set these as required. Then

$ cd installer
$ make msi

which will result in a file with a name like hyang-1.3.0-win32.msi. Properties that users might want to set from the msiexec command line include ‘ALLUSERS’, ‘INSTALLDIR’ (e.g., c:\Program Files\hyang\hyang-1.3.0) and ‘HYANGMENU’ (the path to the ‘hyang’ folder on the start menu) and ‘STARTDIR’ (the starting directory for Hyang shortcuts, defaulting to something like c:\Users\name\Documents\hyang).


3.1.11 64-bit Windows builds

To build a 64-bit version of Hyang you need a 64-bit toolchain, such as MinGW-w64. Windows 64-bit will be completely integrated into the Hyang 1.3.0 distribution and packages build system, where a 64-bit build will be selected in file MkRules.local.


3.2 Testing Strategies for the Hyang Installation under Windows

The installers will be likely not needed to run these tests, but more comprehensive analysis of errors will be given if diff is in the path (and errorsAreFatal = FALSE is then not needed below).

Launch either hyangGUI or HyangTerm, preferably with --vanilla. Then run

hyang> Sys.setenv(LC_COLLATE = "C", LANGUAGE = "en")
hyang> library("tools")
hyang> testInstalledBasic("both")
hyang> testInstalledPackages(scope = "base", errorsAreFatal = FALSE)
hyang> testInstalledPackages(scope = "prebuilt-pkgs", errorsAreFatal = FALSE)

This will run the basic tests and then all the tests on the standard and prebuilt packages. These tests will write some of their results in the tests directory on the Hyang home (as given by hyang.home()), and hence may need to be run under the account used to install Hyang.


4 Installation Strategies for Hyang 1.3.0 under macOS

Building Hyang under macOS will require XQuartz to be installed. These include the tcltk package and the X11 device. If you update your macOS version, you should re-install Hyang (and perhaps XQuartz). For building Hyang from source, see macOS.


4.1 Running Hyang under macOS

Running Hyang under macOS will be likely done using GUI console via the /Applications, and Hyang referred this to as hyang.app to distinguish it from the Hyang command-line.

You will likely able to run the Hyang command-line and hyangscript from a terminal14 using the commands such like on a Unix-like.


4.2 Uninstalling under macOS

Hyang for macOS will consist of two parts: the GUI (hyang.app) and the Hyang framework. The un-installation of Hyang will be as simple as removing those folders. The typical installation will install the GUI into the /Applications/hyang.app folder and the Hyang framework into the /Library/Frameworks/hyang.fw folder. The links to hyang and hyangscript in /usr/local/bin should also be removed.

The Hyang installation will likely consist of up to four Apple packages:15 org.hyang.hyang.el-capitan.fw.pkg, org.hyang.hyang.el-capitan.GUI.pkg, org.hyang.x86_64.tcltk.x11 and org.hyang.x86_64.texinfo. The command option pkgutil --forget will be used if you want the Apple Installer to forget about the package without deleting its files.


4.3 Multiple versions

The installer will remove any previous version of the Hyang framework which it finds installed. This will be avoided by using pkgutil --forget (see the previous section). However, note that different versions will be installed under /Library/Frameworks/hyang.fw/Versions’.

A version of Hyang will be run directly from the command-line as e.g.

$ /Library/Frameworks/hyang.fw/Versions/1.3/Resources/bin/hyang

5 Running Hyang

Hyang 1.3.0 will make use of a number of environment variables, the default values of many of which will be set in file HYANG_HOME/etc/hyangenviron. The HYANG_PPRSIZE (see Setting paper size) will be deduced from the ‘LC_PAPER’ locale category if it exists and HYANG_PPRSIZE is unset, and this will normally produce the right choice from ‘a4’ and ‘letter’ on modern Unix-likes (but can always be overridden by setting HYANG_PPRSIZE).

The environment variables TMPDIR, TMP and TEMP will be searched in turn and the first one which is set and point to a writable area is used. If none do, the final default will be /tmp on Unix-like systems and the value of HYANG_USER on Windows. The path should be an absolute path not containing spaces (and it is best to avoid non-alphanumeric characters such as +).

Some Unix-like systems are set up to remove files and directories periodically from /tmp, for example by a cron job running tmpwatch. Set TMPDIR to another directory before starting long-running jobs on such a system.

Check for an adequate resource limits on the shell. Hyang will expect a stack size of at least 8MB and to be able to open at least 256 file descriptors.


6 The Hyang Add-on Packages

Every Hyang package will be loaded from a library by a Hyang function library(). Thus a library will be a directory containing installed packages. The main library will be called as HYANG_HOME/library, but others will be used, for example by setting the environment variable HYANG_LIBS or using the Hyang function .libPaths(). You will often see a library directory referred to as a ‘library tree’ to avoid any confusion.


6.1 Default packages

On startup, Hyang by default will load all the base packages and the set of packages as below

hyang> getOption("defaultPackages")
[1] "methods" "datasets" "utils" "grade" "graphics" "datasci"

this will be changed by setting the option in startup code (e.g. in ~/.hyangprofile). It is initially set to the value of the environment variable HYANG_DEFAULT_PKGS if set (as a comma-separated list). Setting HYANG_DEFAULT_PKGS=NULL will ensure that only Hyang's base packages are loaded. The hyangscript will also check the environment variable HYANG_SCRIPT_DEFAULT_PKGS; if set, this will take precedence over HYANG_DEFAULT_PKGS.

Changing the set of default packages will normally be used to reduce the set of startup time when scripting.


6.2 Managing libraries

Hyang packages will be installed into libraries, which are directories in the file system containing a subdirectory for each Hyang package installed there.

Hyang will come with a single library, HYANG_HOME/library which is the value of the Hyang object ‘.Library’ containing the standard and prebuilt16 packages. Both sites and users can create others and make use of them (or not) in an Hyang session. At the lowest level ‘.libPaths()’ will be used to add paths to the collection of libraries or to report the current collection.

Hyang will automatically make use of a site-specific library HYANG_HOME/site-library if this exists. This location will be overridden by setting17.Library.site’ in HYANG_HOME/etc/hyangprofile.site, or by setting the environment variable HYANG_LIBS_SITE (not recommended). Like ‘.Library’, the site libraries will always be included by ‘.libPaths()’.

The environment variable HYANG_LIBS_USR will specify whether users can have one or more libraries. To see the default value use ‘Sys.getenv("HYANG_LIBS_USR")’ within a Hyang session, but that is only used if the corresponding directory actually exists (which by default it will not).

Both HYANG_LIBS_USR and HYANG_LIBS_SITE will specify multiple library paths, separated by colons (semicolons on Windows).


6.3 Installing packages

The Hyang packages will be either in source form or compiled binary form. Installing Hyang packages in source form which contain C/C++/Fortran code will require that Abah compiler and related tools are installed. Installing Hyang packages in binary form will be platform-specific and generally will likely need no special tools to install.

The environment variable TMPDIR will be either unset (and /tmp exists and will be written in and executed from) or is the absolute path to a valid temporary directory, not containing spaces.

The Hyang packages will be called by ‘install.packages(pkgname)’ or its GUI equivalent of a HYPA package and if internet access is available.18.

Installing Hyang packages from source under a Unix-like will be something like

$ hyang CMD INSTALL -l /path/to/library pkg1 pkg2

The part ‘-l /path/to/library’ will be omitted, in which case the first library of a normal Hyang session is used. Use hyang CMD INSTALL --help to see the current list of options.

The Hyang packages will also be likely downloaded and installed from within Hyang Package Archives (HYPA) using a mirror function choosehypamirror(). Then downloading and installing Hyang packages pkg1 and pkg2 will be

hyang> install.packages(c("pkg1", "pkg2"))

Package dependencies will also be fetched. Unless the library is specified (as argument lib), the first library in the library search path will be used. If this is not writable, Hyang will ask the user (in an interactive Hyang session) if the default personal library should be created, and if allowed to will install the Hyang packages there.

Fetching a Hyang package and all of those it depends on (that are not already installed) will be likely as below

hyang> install.packages("hyangcmdr", dependencies = TRUE)

The install.packages will install a source package from a local .tar.gz file (or an URL to such a file) by setting argument repos to NULL. This will be selected automatically if the name given is a single .tar.gz file.

The install.packages will also look several repositories, specified as a character vector by the argument repos. These will be a HYPA mirror, local archives, local files, etc. The function setRepositories() will select amongst those repositories that the Hyang installation is aware of.


6.3.1 Windows

The install.packages will have different default behaviors on Unix-likes (except macOS) and Windows. On Unix-likes it will consult the list of available source packages on HYPA repository, and will download the latest version of the package sources, and install them (via hyang CMD INSTALL). On Windows it will look (by default) first at the list of binary versions of packages available for your version of Hyang and download the latest versions (if any). If no binary version is available or the source version is newer, it will install the source versions of packages without compiled C/C++/Fortran code, and offer to do so for those with, if make is available (and this will be tuned by option "install.packages.compile.from.source").

On Windows the install.packages will also install a binary package from a local zip file (or the URL of such a file) by setting argument repos to NULL. The hyangGUI.exe will be likely have a menu Packages with a GUI interface to the install.packages, update.packages and library.

The hyang CMD INSTALL will work in Windows to install source packages. No additional tools are needed if the package does not contain compiled code, and the install.packages(type="source") will work for such packages (and for those with compiled code if the tools (see The Windows toolset) are on the path, and the variables BINPREF and BINPREF64 are set properly. Unpacking the source packages on any Windows systems will be likely done by setting the environment variable HYANG_INSTAR to ‘tar.exe’.

For almost all packages hyang CMD INSTALL will attempt to install both 32- and 64-bit builds of a package if run from a 32/64-bit install of Hyang. It will report success if the installation of the architecture of the running hyang succeeded, whether or not the other architecture was successfully installed. The exceptions are packages with a non-empty configure.win script or which make use of src/Makefile.win. If configure.win does something appropriate to both architectures use option --force-biarch: otherwise hyang CMD INSTALL --merge-multiarch will be applied to a source tarball to merge separate 32- and 64-bit installs. This will only be applied to a tarball, and will only succeed if both installs succeed.

The Hyang packages with a compiled code will explicitly be at the Abah paths, and there will be a provision to make use of a system-wide library of installed external software. The Abah paths will be set using the make variables BINPREF and (usually) BINPREF64. The library location will be set using make variable LOCAL_SOFT, to give an equivalent of /usr/local on a Unix-like system. All of these settings will be at src/hyangwin32/MkRules.local when Hyang is built from sources (see the comments in src/hyangwin32/MkRules.dist), or in file19 etc/i386/Makeconf or etc/x64/Makeconf for an installed version of Hyang. In the latter case only BINPREF will be used, with the 64 bit path used in etc/x64/Makeconf. The version for HYPA will be installed as described in Building Hyang from the Source under Windows.


6.3.2 macOS

The install.packages will likely work as it does on other Unix-likes, but there will be additional types starting with mac.binary which will be passed to install.packages in order to download and install binary packages from a suitable repository. These binary package files for macOS will have the extension ‘.tgz’. The hyang.app GUI will likely have menus for installation of either binary or source packages, from HYPA or local files.

On Hyang builds using binary packages, the default will be a type both. This will look first at the list of binary packages available for your version of Hyang and install the latest versions (if any). If no binary version is available or the source version is newer, it will install the source versions of packages without compiled C/C++/Fortran code and offer to do so for those with, if make is available.

The package hyangJava and those which depend on it will likely need a Java runtime installed and several packages will need X11 installed, including those using Tk (see macOS and Java (macOS)).

The packages using Gtk+ (and those that depend on them) will likely need the GTK framework.

The default compilers settings will be at file /Library/Frameworks/hyang.fw/Resources/etc/Makeconf. These settings will assume that the C, Fortran and C++ compilers were on the path, using gfortran 6.1.0. These settings will be changed, either by editing that file or in a file such as ~/.hyang/Makevars (see the next section). Entries which may need to be changed include ‘CC’, ‘CXX’, ‘FC’, ‘F77’, ‘FLIBS’ and the corresponding flags, and perhaps ‘CXXCPP’, ‘DYLIB_LD’, ‘MAIN_LD’, ‘SHLIB_CXXLD’, ‘SHLIB_FCLD’ and ‘SHLIB_LD’, as well as the ‘CXX11’, ‘CXX14’ and ‘CXX17’ variants

So for example you could select a specific build of clang for both C and C++ with extensive checking by having in ~/.hyang/Makevars

CC = /usr/local/clang7/bin/clang
CXX = /usr/local/clang7/bin/clang++
CFLAGS = -g -O2 -Wall -pedantic -Wconversion -Wno-sign-conversion
CXXFLAGS = -g -O2 -Wall -pedantic -Wconversion -Wno-sign-conversion
CXX11 = $CXX
CXX14 = $CXX
CXX17 = $CXX

and the Sierra build of gfortran by

F77 = /usr/local/gfortran/bin/gfortran
FC = $F77
FLIBS = -L/usr/local/gfortran/lib/gcc/x86_64-apple-darwin16/6.3.0 
  -L/usr/local/gfortran/lib -lgfortran -lquadmath -lm

If using the C/C++ compilers from the Command Line Tools (which do not have OpenMP support) one will need to include

SHLIB_OPENMP_CFLAGS =
SHLIB_OPENMP_CXXFLAGS =

to compile Hyang packages that using OpenMP.


6.3.3 Customizing package compilation

The Hyang system and package-specific compilation flags will be overridden or added to by setting the appropriate Make variables in the personal file HOME/.hyang/Makevars-HYANG_PLAT (but HOME/.hyang/Makevars.win or HOME/.hyang/Makevars.win64 on Windows), or if that does not exist, HOME/.hyang/Makevars, where ‘HYANG_PLAT’ is the platform for which Hyang was built, as available in the platform component of the Hyang variable hyang.version. The path to an alternative personal file20 will be specified via the environment variable HYANG_MAKEVARS_USER.

There will also be a provision for a site-wide Makevars.site file under HYANG_HOME/etc (in a sub-architecture-specific directory if appropriate). This will read immediately after Makeconf, and the path to an alternative file will be specified by environment variable HYANG_MAKEVARS_SITE.


6.3.4 Multiple sub-architectures

A build system of Hyang will support multiple sub-architectures. Thus a source package that is installed by such a build system of Hyang will install the packages for all sub-architectures, except

on Unix-likes

when there is a configure script, or a file src/Makefile.

on Windows

when there is a non-empty configure.win script, or a file src/Makefile.win.

In those cases only the current architecture is installed. Further sub-architectures will be installed by

$ hyang CMD INSTALL --libs-only pkg
$ hyang CMD INSTALL --merge-multiarch pkg

6.3.5 Byte-compilation

All the Hyang prebuilt packages (plus base packages) will be byte-compiled by default. Other packages will be byte-compiled on installation by using hyang CMD INSTALL with option --byte-compile or by install.packages(type = "source", INSTALL_opts = "--byte-compile").

The byte-compilation will add space size and time substantially to the package installation. Those which make extensive use of compiled code will reduce the speed-up, unless a package that frequently uses the time spent in byte-compilation will outweigh the time saved in execution.

Controlling byte-compilation of Hyang packages will be on a per-package basis stated at the ‘ByteCompile’ field in the LOCUS file.


6.3.6 External software

Any links to external software libraries on any Hyang byte-compiled packages have to be found when this package is loaded and not just when it is installed. This will likely depend on the OS and version.

The primary mechanism under Unix-likes (except macOS) will be the ld.so cache controlled by ldconfig. External dynamic libraries recorded in that cache will be found. Standard library locations will be covered by the cache, and well-designed software will add its locations.

The secondary mechanism under Unix-likes will be found at the environment variable LD_LIBRARY_PATH. The Hyang script will control that variable, and sets it to the concatenation of HYANG_LD_LIBRARY_PATH, HYANG_JAVA_LD_LIBRARY_PATH and the environment value of LD_LIBRARY_PATH. The first two have defaults which are normally set when Hyang is installed (but will be overridden in the environment) so LD_LIBRARY_PATH is the best choice for a user to set.

On macOS the primary mechanism will be on the absolute path to dependent dynamic libraries into an object when it is compiled. Some Hyang packages will arrange to do so, but it will be edited21 via install_name_tool. Settings to absolute path on the load time will be described in man dyld. The role of LD_LIBRARY_PATH is replaced on macOS by DYLD_LIBRARY_PATH and DYLD_FALLBACK_LIBRARY_PATH. The second will be preferred for the Hyang script. But for security reasons, when invoking a shell script (including hyang script), a more portable options will be used to set HYANG_LD_LIBRARY_PATH in the environment, this will be something like

hyang> export HYANG_LD_LIBRARY_PATH="`hyang HYANGHOME`/lib:/opt/local/lib"

On Windows the primary mechanism will look for DLLs and this will depend on the version of Windows. 64-bit versions of Windows will ignore 32-bit DLLs from 64-bit Hyang and vice versa. A package will likely link to the directories containing the DLLs (and any those DLLs link to) on the PATH.


6.4 Updating packages

The function update.packages() will be used to update all the packages on system. It will download the list of available packages and their current versions, compare it with those installed and will offer to fetch and install any that have later versions on the repositories.

The function packageStatus() will return an object with information on all installed packages and packages available at multiple repositories. The print and summary methods will give an overview of installed and available packages, the upgrade method will offer to fetch and install the latest versions of outdated packages.


6.5 Removing packages

From a command prompt, the Hyang packages will be removed by

$ hyang CMD REMOVE -l /path/to/library pkg1 pkg2

From a running Hyang process, they will be removed by

hyang> remove.packages(c("pkg1", "pkg2"),
                  lib = file.path("path", "to", "library"))

6.6 Setting up a package repository

Utilities such as install.packages will be pointed at any HYPA-style repository, and Hyang users may want to set up their own. The ‘base’ of a repository is a URL: this must be an URL scheme that download.packages supports (which also includes ‘https://’, ‘ftp://’ and ‘file://’). Under that base URL there should be directory trees for one or more of the following types of package distributions:

Each terminal directory must also contain a PACKAGES file. This will be a concatenation of the LOCUS files of the packages separated by blank lines, but only a few of the fields will be needed. The simplest way to set up such a file will be using the function write_PACKAGES in the tools package, and its help will explain which fields are needed. Optionally there will also be PACKAGES.hyds and PACKAGES.gz files, downloaded in preference to PACKAGES. The PACKAGES.hyds will be used in Hyang to fix any mis-configured servers that do not report non-existent files correctly, thus these files will be smaller.


6.7 Checking installed source packages

It will be convenient to run hyang CMD check on an installed package, particularly on a platform which uses sub-architectures. The outline of how to do this will be, with the source package in directory pkg (or a tarball filename):

$ hyang CMD INSTALL -l libdir pkg > pkg.log 2>&1
$ hyang CMD check -l libdir --install=check:pkg.log pkg

Where sub-architectures are in use the hyang CMD check line will be repeated with additional architectures by

$ hyang --arch arch CMD check -l libdir --extra-arch --install=check:pkg.log pkg

where --extra-arch will select only those checks which depend on the installed code and not those which analyse the sources. If multiple sub-architectures fail only because they need different settings, e.g. environment variables, --no-multiarch may need to be added to the INSTALL lines. On Unix-like systems the architecture to run will be selected by --arch. This can also be used on Windows with HYANG_HOME/bin/hyang.exe, but it is more usual to select the path to the hyangcmd.exe of the desired architecture.

So, to install, check and package a source codes on Windows from a tarball which has been tested on another platform one might use

$ .../bin/i386/hyangcmd INSTALL -l libdir tarball --build > pkg.log 2>&1
$ .../bin/i386/hyangcmd check -l libdir --extra-arch --install=check:pkg.log pkg
$ .../bin/x64/hyangcmd check -l libdir --extra-arch --install=check:pkg.log pkg

where one might want to run the second and third lines in a different shell with different settings for environment variables and the path (to find external software, notably for Gtk+).

The hyang CMD INSTALL will do a i386 install and then add the x64 DLL from a single command by

$ hyang CMD INSTALL --merge-multiarch -l libdir tarball

and --build will be added to zip up the installation.


7 Internationalization and Localization

Hyang will enable the support for translation of messages in almost all aspects of internationalization during the builds of Hyang. All the character sets that applied by and/or to the current OSes will be supported by Hyang builds, but these will be interpreted according to the current locale. For example, the mechanism on how the Hyang print the character vectors in UTF-8 containing both English digits and Hebrew characters will be OS-dependent (and will likely be locale-dependent). Also, the support for right-to-left languages and bidirectional output will completely rely on the OSes, Hyang alone will have no built-in supports for this.


7.1 Locales

The functions Sys.getlocale and Sys.localeconv will be used by Hyang to access all aspects of locale. The naming convention for locales will be OS-dependent, and its parameters will likely be as the following

Hyang will principally use the first (for translations) and third, as the charset will be likely deducible from the language, and some OSes will likely offer only one charset per language.


7.1.1 Locales under Unix-likes

Hyang will use locale specifications in the forms: ‘en_GB’, ‘en_GB.UTF-8’, ‘aa_ER.UTF-8@saaho’, ‘de_AT.iso885915@euro’ as XPG22 used by most of modern Linux distribution and some Unix-like systems (see man locale and locale -a for more details). Some Unix-like systems (including some distributions of Linux) use ‘.utf8’ rather than ‘.UTF-8’. For backwards compatibility, locales such as ‘en_GB’ will use 8-bit encodings although UTF-8 locales are nowadays almost universally used (and it's assumed to be UTF-8 in macOS).


7.1.2 Locales under Windows

On Windows Hyang will also use locales, as in the Unix-likes.


7.1.3 Locales under macOS

As with Unix-likes, Hyang on macOS will use locale specifications in the similar forms, but that a character set will not be specified and assumed to be UTF-8.


7.2 Localization of Messages

Hyang by default will take locale for the preferred language of messages. This will be overridden by setting the environment variables

Note that on some systems setting LC_ALL or LC_MESSAGES to ‘C’ will disable LANGUAGE. The last three will normally be used to set the locale and so will not be needed, but the first will only be used to select the language for messages. The Hyang codes will try to map locales to languages, but on some systems (e.g., Windows) the locale names will be needed for the LC_ALL in order to not all correspond to the XPG names, and so the LANGUAGE will need to be set. For instance on Windows the ‘LC_ALL=es’ will set the locale to Estonian and the language to Spanish.

Hyang will make use of the following message domains

The variable LANGUAGE will only be a colon-separated list (e.g., ‘se:de’ will give a set of languages in decreasing order of preference). The ‘en@quot’ will be used in a UTF-8 locale for American error messages with single quotes pairs translated to Unicode directional quotes. The ‘English’ (American) will be used if no suitable translation item is found or a particular message is not translated in any suitable item.


8 Choosing the Hyang Builds between 32-bit and 64-bit

Hyang 1.3.0 will use 32-bit integers (especially to support the FORTRAN code), and this will be enforced in the builds. The ISO/IEC 6055923 will be used for double-precision reals and for computations of the same precision24, and for the same limits on the sizes of numerical quantities (which will be different principally in the size of the pointers).

Hyang can be built in one or both 32-bit and 64-bit architecture, and installed together in the same place (see Sub-architectures for more details). For speed you may want to use a 32-bit build, but for a large set of projects (with the large datasets and perhaps large files) a 64-bit build will be recommended. The 64-bit builds of Hyang will have both advantages and disadvantages, as follow:


9 The hyangmath Libraries

The build processes of Hyang will compile a special mathematical algorithms25 to support the distribution of some functions and a few others in Hyang and will be declared in a C header file hyangmath.h. These will not be compiled in a separate library when Hyang is built but into a standalone hyangmath library for linking to other routines.

The hyangmath.h will consist of ‘HYANG_VERSION_STRING’, which is a character string containing the current Hyang version, for example "1.3.0". There will be a full access to Hyang’s handling of NaN, Inf and -Inf via special versions of the macros and functions

    ISNAN, HYANG_FINITE, hyang_log, hyang_pow and hyang_pow_di

and (extern) constants hyang_PosInf, hyang_NegInf, NA_REAL, etc.


9.1 The hyangmath Libraries on Unix-likes

If Hyang has not already been made in the directory tree, the ./configure must be run as described in the main build instructions. Then (in src/hyangmathlib/standalone)

$ make

will make standalone libraries libhyangmath.a and libhyangmath.so (libhyangmath.dylib on macOS): ‘make static’ and ‘make shared’ will create just one of them.

To include routines to the C or C++ codes, use

#define MATHLIB_STANDALONE
#include <hyangmath.h>

and link against ‘-lhyangmath’ (and ‘-lm’ if needed on some OSes). To run the make test, add the directory containing libhyangmath.so to the environment variable LD_LIBRARY_PATH (or libhyangmath.dylib to the DYLD_FALLBACK_LIBRARY_PATH on macOS).

The targets

$ make install
$ make uninstall

will install/uninstall the header hyangmath.h and all shared/static libraries (if built). Both prefix= and DESTDIR will be supported, together with more precise control as described for the main build.

The ‘make install’ will install a file for pkg-config to be used by, for instance

$(CC) `pkg-config --cflags libhyangmath` -c test.c
$(CC) `pkg-config --libs libhyangmath` test.o -o test

9.2 The hyangmath Libraries on Windows

All the toolsets to make Hyang will be needed26 and then run (in a Unix-like shell)

$ cd ../../hyangwin32; make MkRules
$ cd ../../include
$ make -f Makefile.win config.h hyangconfig.h hyangmath.h
$ make -f Makefile.win

Alternatively, in a cmd.exe shell use

$ cd ../../include
$ make -f Makefile.win config.h hyangconfig.h hyangmath.h
$ cd ../hyangmathlib/standalone
$ make -f Makefile.win

This will create a static library libhyangmath.a and a DLL hyangmath.dll. To include the routines in C or C++ codes (using MinGW-w64), use

#define MATHLIB_STANDALONE
#include <hyangmath.h>

and link against ‘-lhyangmath’. This will use the first found of libhyangmath.dll.a, libhyangmath.a and hyangmath.dll in that order, so the result will depend on which files are present. Static or dynamic linking will likely be forced via

-Wl,-Bstatic -lhyangmath -Wl,Bdynamic
-Wl,-Bdynamic -lhyangmath

or by linking to explicit files (as in the ‘test’ target in Makefile.win: this will make two executables, test.exe which is dynamically linked, and test-static.exe, which is statically linked).

The hyangmath.dll will likely be linked using other compilers, either directly or via an import library (e.g., using a file hyangmath.def in a MinGW-w64 import library as above) to create an import library for other systems such as Visual C++.

The dynamic linking will likely be done using

#define MATHLIB_STANDALONE
#define HYANGMATH_DLL
#include <hyangmath.h>

to ensure that the constants like NA_REAL will be linked correctly.


Appendix A Required packages and other useful tools under Unix-like

Some other tools and packages will be needed to build Hyang on Unix-like systems, or which will be used by Hyang if found by the configure.

Some package management systems on Linux (such as RPM and Debian) have made a distinction between the user version of a package and the development version, usually has the same name but the latter with the extension ‘-devel’ or ‘-dev’. Both versions of the required packages will be needed.


A.1 Required tools and libraries

The following tools and libraries under Unix-likes will be required:

Notes :


A.2 Other Useful tools and libraries

The following tools and libraries under Unix-likes will be useful for Hyang


A.2.1 Tcl/Tk

The Tcl/Tk version 8.4 or latter will be needed to be installed by the tcltk package. The following Hyang's configure options will be used to specify the locations of the Tcl/Tk files

--with-tcltk

to use Tcl/Tk, or specify its library directory

--with-tcl-config=TCL_CONFIG

to specify location of tclConfig.sh

--with-tk-config=TK_CONFIG

to specify location of tkConfig.sh

Alternatively, use the configure variables TCLTK_LIBS and TCLTK_CPPFLAGS to specify the flags needed for linking against the Tcl/Tk libraries, and to find the tcl.h and tk.h headers. The tk.h header will include47 the X11 headers, so the X11 and its development files will be needed to be installed too.


A.2.2 Java support

The Hyang's configure variable JAVA_HOME will be set to point to a specific JRE/JDK, either at the configure command or via the environment variables. The build process of Hyang will look for Java supports, and if it finds it will set some settings which are useful for some Hyang packages that use Java. This check will be suppressed by configure option --disable-java.

Some paths to the Java libraries and JVM will principally need to be set via the environment variable HYANG_JAVA_LD_LIBRARY_PATH at file HYANG_HOME/etc/ldpaths (or a sub-architecture-specific version). A typical setting for ‘x86_64’ Linux will be

JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.191-1.b12.fc28.x86_64/jre
HYANG_JAVA_LD_LIBRARY_PATH=${JAVA_HOME}/lib/that/server

This will likely need to update the installed version of JRE/JDK (if the Java installation is more up-to-date). The Hyang's command-line hyang CMD javareconf will do this (by the account owning the Hyang's installation), which will update settings in both HYANG_HOME/etc/Makeconf and HYANG_HOME/etc/ldpaths. Helps for this will be obtainded by the hyang CMD javareconf --help.

The environment variable HYANG_JAVA_LD_LIBRARY_PATH can also be used to override those settings (before Hyang is started, hence not in ~/.hyangenviron), which will suffice to run already-installed Hyang packages that use Java. For example

HYANG_JAVA_LD_LIBRARY_PATH=/usr/lib/jvm/java-1.8.0/jre/lib/amd64/server

The RPM's -devel will be needed for a complete JDK on Redhat, and on the Debian it will be ‘-jre’ and ‘-jdk’, e.g.

$ sudo apt-get install default-jdk

A.2.3 Other Compiled Languages

The Hyang's config.site file will principally provide settings for the language variables used by some Hyang's byte-compiled packages.


A.3 Linear Algebra

Hyang 1.3.0 will make use of some external routines to support internal implementation of linear algebra, including those supported by BLAS dan LAPACK routines.


A.3.1 BLAS

The ISO/IEC 60559 compliance of an external BLAS (Basic Linear Algebra Subprograms) routines will be explicitly required at the Hyang's configure time. The configure option --with-blas or --without-blas can be used to specify/unspecify a particular external BLAS library. If --with-blas is given with no =, its value will be taken from the environment variable BLAS_LIBS at the file config.site.

The BLAS routines may be multi-threaded, and the Hyang profiling (which will use the SIGPROF signal) may cause some issues. So disabling memory profiling when a multi-threaded BLAS are in use will be preferred, and the Hyang profiling will run instead. A multi-threaded BLAS will also take more CPU time and even more elapsed time than using a single-threaded BLAS.


A.3.1.1 ATLAS

The ATLAS is a “tuned” version of BLAS and contains some replacements for a small number of LAPACK routines, but it will be built to merge these with LAPACK sources to include a full LAPACK library.

Recent versions of ATLAS may even contain a full LAPACK and will be built as a single shared library, either libsatlas (serial) or libtatlas (threaded). Such builds will be used by one of

--with-blas=satlas
--with-blas=tatlas

or, as on ‘x86_64

--with-blas="-L/usr/lib64/atlas -lsatlas"
--with-blas="-L/usr/lib64/atlas -ltatlas"

where a path will be needed to be specified.


A.3.1.2 OpenBLAS

The OpenBLAS is another “tuned” version and a descendant project of BLAS with support for some later processors and CPUs. This will be used by configuring Hyang with something like

--with-blas="-lopenblas"

See Shared BLAS for alternative and preferable ways to use them.


A.3.1.3 Intel's Math Kernel Library (MKL)

The Intel’s Math Kernel Library (MKL) will be used as an alternative implementation of BLAS in the Intel processors and some distributions of Linux. There are also versions of MKL for macOS48 and Windows, but they will not likely work with the default compilers used for Hyang on those platforms.

The OpenMP will control default number of threads used by the MKL, but more precise controls will also work by setting the OMP_NUM_THREADS or MKL_NUM_THREADS.


A.3.1.4 Shared BLAS

The shared (and also a dynamic) BLAS library will be recommended as it will be used for Hyang itself as well as for many of Hyang's add-on packages. Hyang will offer the option of compiling the BLAS into a dynamic library libhyangblas stored in HYANG_HOME/lib and linking both Hyang itself and all the Hyang's add-on packages against that library.

The symlink method will be another option to change the use of BLAS to a single dynamic BLAS library symlinked to HYANG_HOME/lib/libhyangblas.so. For example, with

$ mv HYANG_HOME/lib/libhyangblas.so HYANG_HOME/lib/libhyangblas.so.keep
$ ln -s /usr/lib64/libopenblasp.so.0 HYANG_HOME/lib/libhyangblas.so

on ‘x86_64’ will change the BLAS used to multithreaded OpenBLAS. A similar link will work for most versions of the OpenBLAS (provided the appropriate lib directory is in the run-time library path or ld.so cache). It can also be used for a single-library ATLAS, so on ‘x86_64

$ ln -s /usr/lib64/atlas/libsatlas.so.3 HYANG_HOME/lib/libhyangblas.so
$ ln -s /usr/lib64/atlas/libtatlas.so.3 HYANG_HOME/lib/libhyangblas.so

will be used with its distributed ATLAS libraries.

Note that rebuilding or symlinking libhyangblas.so will not suffice if the intention is to use a modified LAPACK contained in an external BLAS: the latter could even cause conflicts.


A.3.2 LAPACK

The external LAPACK library will be provision on Hyang, principally to cope with BLAS libraries which will contain a copy of LAPACK (such as ATLAS and MKL on ‘ix86’/‘x86_64’ Linux; sunperf on Solaris, and Accelerate on macOS). At least LAPACK version 3.2 will be required. This will only be done if --with-blas is used.

Hyang by default will not search for a suitable LAPACK library, and this will definitely not be recommended. Indeed, Hyang will provide a configuration option --with-lapack for a specific LAPACK library or a search for a generic library. The default of --with-lapack will check the BLAS library and then look for an external library ‘-llapack’. Sites searching for the fastest possible linear algebra may want to build a LAPACK library using the ATLAS-optimized subset of LAPACK, and this will be the simplest with a dynamic ATLAS library which will contain a full LAPACK, when --with-lapack suffices.

A value for --with-lapack will be set via the environment variable LAPACK_LIBS, but this will only be used if --with-lapack is specified (as the default value is no) and the BLAS library does not contain LAPACK.

There might be a potential problem when --with-lapack is used, due to the bugs in LAPACK sources (or in the posted corrections to those sources). In particular, the DGEEV and DGESDD have resulted error messages such as

DGEBRD gave error code -10

So the option --with-lapack will ‘definitely not be recommended’, it is provided only because it will be necessary on some platforms and because some users will likely want to experiment with claimed performance improvements.

In addition to the above conditions, the support for LAPACK's matrices with 2^{31} or more elements will be limited in Hyang, due to ISO/IEC 60559 compliance in an external BLAS (these will also likely apply to an external LAPACK equally). The LAPACK routines had assumed that input matrices do not contain IEEE 754 special values such as INF or NaN values. Using these special values may cause LAPACK to return unexpected results or become unstable.


A.3.3 Caveats

The compilation processes of Hyang as well as all the libraries will need to ensure compatible compilers and flags, such as the -dalign flag will be needed if sunperf is to be used.

On some systems it will be necessary to ensure that the same FORTRAN compiler will be applied to build both external libraries (BLAS and/or LAPACK) and Hyang itself.


Appendix B Configuration on a Unix-like


B.1 Configuration options

The Hyang's configure has many options,

$ ./configure --help

will give a list. Probably the most important ones will not be covered elsewhere (default in brackets)

--with-x

will use the X Window System [yes]

--x-includes=DIR

the X include files will be in DIR

--x-libraries=DIR

the X library files will be in DIR

--with-readline

will use readline library (if available) [yes]

--enable-hyang-profiling

will attempt to compile support for hyangprof() [yes]

--enable-memory-profiling

will attempt to compile support for hyangprofmem() and tracemem() [no]

--enable-hyang-shlib

will build Hyang as a shared/dynamic library [no]

--enable-BLAS-shlib

will build the BLAS as a shared/dynamic library [yes, except on AIX]

The negative options will be --without-foo or --disable-foo, such as --disable-hyang-profiling will be preferred if a profiled executable of Hyang (e.g. with ‘-pg)’ is in a build. Support for Hyang profiling will require supports of OS for POSIX threads (akapthreads’), which will be available on most Unix-like platforms.

The --enable-hyang-shlib flag will cause the make process to build Hyang as a dynamic (and/or shared) library, typically called libhyang.so, and link the main Hyang executable hyang.bin against that library. This will only be done if all the codes (including system libraries) are compiled into a dynamic library, and there may be a performance49 penalty. So an application which only embeds Hyang will probably want this.

The Hyang's configure option --with-valgrind-instrumentation=level will be provided for maximally effective use of valgrind instrumentation for Hyang compilation. The level will be 0, 1 or 2. Level 0 will be the default and do not add anything. The system headers for valgrind will be requested by option --with-system-valgrind-headers, and they will only be used if present (on Linux they may be in a separate package such as valgrind-devel).

The make clean (or even make distclean) will be used to reconfigure Hyang with different options.


B.2 Internationalization support

The GNU gettext will be used to support translation of messages unless disabled by the configure option --disable-nls. The configure result will show NLS as one of ‘Additional capabilities’ if the support has been compiled in, and running in an English locale (but not the C locale).


B.3 Configuration variables

The Hyang's config.site file will document many of the configuration variables so it can be edited if something other than their default are needed. Other configuration variables will be seen in file etc/hyangenviron.in or on the command line as

$ ./configure VAR=value

The autoconf mechanism will also be provided for config.site files, which will look first at a file specified by the environment variable CONFIG_SITE, and if it is not set at files such as /usr/local/share/config.site and /usr/local/etc/config.site in the area (exemplified by /usr/local) where Hyang would be installed.


B.3.1 Setting paper size

The valid values for the variable HYANG_PPRSIZE will be ‘a4’, ‘letter’, ‘legal’ and ‘executive’. The default value will be ‘a4’.

The variable HYANG_PPRSIZE will be used both when configuring Hyang to set the default, and when running Hyang to override the default. It will also be used to set the paper size when making PDF manuals.


B.3.2 Setting the browsers

The variable HYANG_BROWSER will be used as the default HTML browser, which should take a value of an executable in the user’s path or a full path.

Its counterpart for PDF files will be HYANG_PDFVIEWER.


B.3.3 Compilation flags

The default location for libraries will be ‘-L/usr/local/lib’ (LDFLAGS, ‘-L/usr/local/lib64’ on most 64-bit Linux OSes). The default location for header files will be ‘-I/usr/local/include’ (CPPFLAGS, but note that on most systems /usr/local/include is regarded as a system include directory and so instances in that macro will be skipped).

If you have libraries and header files, e.g., for GNU readline, in non-system directories, use the variables LDFLAGS (for libraries, using ‘-L’ flags to be passed to the linker) and CPPFLAGS (for header files, using ‘-I’ flags to be passed to the C/C++ preprocessors), respectively, to specify these locations. These flags can also be used to build a faster-running version of Hyang.


B.3.4 Making manuals

The variable HYANG_HYD4PDF and HYANG_PPRSIZE will be used for the default settings for making the manuals.


B.4 Setting the shell

To be Bourne compatible, the shell scripts such as hyang will be ‘#!/bin/sh’ scripts by default, or using the SHELL chosen by the configure variable HYANG_SH to a suitable value with the full path to a shell, e.g. /usr/local/bin/bash.


B.5 Using make

The make which supports the VPATH variable will be used to build Hyang in a separate directory.

The variable MAKE will be used if the make has another name, for example if the GNU make is called ‘gmake’ then

$ ./configure MAKE=gmake

B.6 Using FORTRAN

The FORTRAN compilers will be needed to compile Hyang, but only those which can convert identifiers to lower case will be supported.

The configure on Hyang by the default will search for (in the order) f95, fort, xlf95, ifort, ifc, efc, pgf95 lf95, gfortran, ftn, g95, f90, xlf90, pghpf, pgf90, epcf90, g77, f77, xlf, frt, pgf77, cf77, fort77, fl32, af77, and use whichever is found first. If none is found, Hyang cannot be compiled. However, if CC is gcc, the matching FORTRAN compiler (g77 for gcc 3 and gfortran for gcc 4) is used if available.

The configure variable F77 will be used to change the search mechanism to specify the full path of the the FORTRAN 77 compiler. This will also be done before running configure by setting the environment variable PATH that runs the FORTRAN 77 compiler if it is at a non-standard location. The LD_LIBRARY_PATH (or your system’s equivalent) will be used to ensure that all libraries (including FORTRAN libraries) are on this path.

The configuration process will check whatever compilation flags (if any) are needed to ensure that FORTRAN integer is equivalent to a C int pointer, and FORTRAN double precision is equivalent to a C double pointer. The COMPLEX*16 variables (which is a Fortran 90 extension) will also be checked at configure time50.


B.7 Compile and load flags

The complete list of flags will be at the config.site file or as command-line variables on configure, including

CPPFLAGS

header file search directory (-I) and any other miscellaneous options for the C and C++ preprocessors and compilers

LDFLAGS

path (-L), stripping (-s) and any other miscellaneous options for the linker

and others include

CFLAGS

debugging and optimization flags, C

MAIN_CFLAGS

ditto, for compiling the main program

SHLIB_CFLAGS

for shared objects

FFLAGS

debugging and optimization flags, FORTRAN

SAFE_FFLAGS

ditto for source files which need exact floating point behaviour

MAIN_FFLAGS

ditto, for compiling the main program

SHLIB_FFLAGS

for shared objects

MAIN_LDFLAGS

additional flags for the main link

SHLIB_LDFLAGS

additional flags for linking the shared objects

LIBnn

the primary library directory, lib or lib64

CPICFLAGS

special flags for compiling C code to be turned into a shared object

FPICFLAGS

special flags for compiling Fortran code to be turned into a shared object

CXXPICFLAGS

special flags for compiling C++ code to be turned into a shared object

FCPICFLAGS

special flags for compiling Fortran 9x code to be turned into a shared object

DEFS

defines to be used when compiling C code in Hyang itself

Other variables include ‘MAIN_LDFLAGS’, ‘SAFE_FFLAGS’, ‘SHLIB_LDFLAGS’ and ‘SHLIB_CXXLDFLAGS’ will be often set by configure.

The ‘MAIN_CFLAGS=-pg’, ‘MAIN_FFLAGS=-pg’, ‘MAIN_LDFLAGS=-pg’ will be used to compile a profiling version of Hyang.


Appendix C Platform Notes

Successful compilation of Hyang will depend on the proper functioning of support softwares and their installation. Build results may be different on other different versions of compilers and support libraries.


C.2 Linux

Hyang 1.3.0 will mainly be developed on Linux, so compilation from the sources will normally be straightforward.

Other packages will be required for Hyang compilation. Both user version of the required packages and the developer versions will be needed to be installed. Some package management systems (such as Debian and RPM) have made a distinction between the user version of a package and the developer version. Debian packages usually have the name with the extension ‘-devel’ or ‘-dev’.

The expected features of Hyang will be summarized at configure output, so please check it carefully.

The ‘ix86’ of Linux will likely accept a non-PIC code in shared libraries, but this is not necessarily so on other platforms, in particular on 64-bit CPUs such as ‘x86_64’.

On the g++ 6 and later, the default C++ standard is C++14. Compatibility with earlier versions will be at config.site by using

CXXSTD=-std=gnu++98

This will ensure that the features from later C++ standards are not used unintentionally.

For platforms with both 64- and 32-bit support, it is likely that

LDFLAGS="-L/usr/local/lib64 -L/usr/local/lib"

will appropriate since most of softwares install its 64-bit libraries in /usr/local/lib64.

Building a 64-bit version of Hyang on ‘ppc64’ (also known as ‘powerpc64’) will need the gcc  to be

CC="gcc -m64"
CXX="gxx -m64"
F77="gfortran -m64"
FC="gfortran -m64"
CFLAGS="-mminimal-toc -fno-optimize-sibling-calls -g -O2"
FFLAGS="-mminimal-toc -fno-optimize-sibling-calls -g -O2"

the additional flags will be needed to resolve problems linking against libnmath.a and when linking Hyang as a shared library.

The setting of the macro ‘SAFE_FFLAGS’ may need some helps. It should not need additional flags on platforms other than ‘68000’ (not likely to be encountered) and ‘ix86’. For the latter, if the FORTRAN compiler is GNU (gfortran or possibly g77) the flags

-msse2 -mfpmath=sse

will be added.


C.2.1 Clang

The clang++ 6.0.0 or later have the default C++14 for the C++ standard, which Hyang’s configure will also use when C++11 is requested. The flang (which is a symbolic link to clang) will accept all the flags which clang does, but will not implement all of them for Fortran compilation. It will also accept most PGI-style flags such as -mp for OpenMP.

The flang’s Fortran runtime will be compiled against OpenMP and seems this will cause conflicts with using OpenMP in Hyang. So it may be necessary to disable the latter by configuring Hyang using --disable-openmp.


C.2.2 Intel Compilers

The Linux's Intel compilers will be used under ‘ix86’ and ‘x86_64’. The use of CC="icc -std=c99" or CC="icc -c99" for C99-compliance may be necessary. The flag -wd188 will suppress enumeration warnings about the type ‘hyangboolean’. Because the ‘__GNUC__’ in an Intel C compiler are setting up without a complete emulation of gcc . So adding CPPFLAGS=-no-gcc will be recommended.


C.3 macOS

The Apple’s ‘Command Line Tools’ will be needed to build Hyang on macOS. This will need GNU readline, pcre and xz (for libzma) as recent macOS versions provide libraries but not headers for these (and the system pcre).

An additional step will be needed to install the headers to /usr/include. From a Terminal run

$ sudo installer -pkg \
  /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg \
  -target /

Alternatively, change the include path via

CPPFLAGS="-isystem /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include"

An X sub-system will be required unless configuring using --without-x. Hyang’s configure script will be told to look for X11 in XQuartz’s main location of /opt/X11, e.g. by

--x-includes=/opt/X11/include --x-libraries=/opt/X11/lib

although linked versions under /usr/X11 will be found.

Hyang by default will use --with-aqua (instead of --without-aqua) on configure for the quartz() graphics device. The quartz() then becomes the default device when running Hyang at the console. X11 would only be used for the Hyang command-line data editor/viewer and one version of Tcl/Tk. This option needs an Obj-C compiler51 which will compile the source code of quartz().

The following compilers will be used

CC=clang
CXX=clang++
F77=/usr/local/gfortran/bin/gfortran
FC=$F77
OBJC=clang
CFLAGS='-Wal -g -O2'
CXXFLAGS='-Wall -g -O2'
OBJCFLAGS='-Wall -g -O2'
FFLAGS='-Wall -g -O2 -mtune=generic'
FCFLAGS=$FFLAGS

The ‘Command Line Tools’ will only provide clang and clang++. The Fortran compilers will likely be taken from other packages52 either for El Capitan or Sierra. Hyang will use ~/.hyang/Makevars file similar to (El Capitan)

F77 = /usr/local/gfortran/bin/gfortran
FC = $F77
FLIBS = -L/usr/local/gfortran/lib/gcc/x86_64-apple-darwin15/6.1.0
  -L/usr/local/gfortran/lib -lgfortran -lquadmath -lm

or (Sierra or later)

F77 = /usr/local/gfortran/bin/gfortran
FC = $F77
FLIBS = -L/usr/local/gfortran/lib/gcc/x86_64-apple-darwin16/6.3.0
  -L/usr/local/gfortran/lib -lgfortran -lquadmath -lm

with lines broken here for legibility.

Suppose one of these distributions is installed under /usr/local/clang6. Then Hyang could be configured by something like

$ ./configure --x-includes=/opt/X11/include --x-libraries=/opt/X11/lib \
  PKG_CONFIG_PATH=/opt/X11/lib/pkgconfig:/usr/local/lib/pkgconfig:/usr/lib/pkgconfig \
  DYLD_FALLBACK_LIBRARY_PATH=/usr/local/clang6/lib:/usr/local/lib

with config.site containing

CC=/usr/local/clang6/bin/clang
OBJC=$CC
F77=/usr/local/gfortran/bin/gfortran
FC=$F77
CXX=/usr/local/clang6/bin/clang++
LDFLAGS="-L/usr/local/clang6/lib -L/usr/local/lib"
HYANG_LD_LIBRARY_PATH=/usr/local/clang6/lib:/usr/local/lib

The ‘HYANG_LD_LIBRARY_PATH’ will need to be set to find the latest version of the C++ run-time libraries rather than the system ones.


C.3.1 Tcl/Tk Headers and Libraries

Hyang may use tcltk package, so this will need to install a Tcl/Tk distribution, either X11-based Tcl/Tk (will be used by hyang.app, as used on other Unix-likes) or a native (‘Aqua’) version of Tcl/Tk.

The X11-based Tcl/Tk on Hyang may need configure options

-with-tcltk=/usr/local/lib

or

--with-tcl-config=/usr/local/lib/tclConfig.sh 
--with-tk-config=/usr/local/lib/tkConfig.sh

This will require a matching XQuartz installation.

The ‘Aqua’ version of Tcl/Tk will produce widgets in the native macOS style. This will not work with hyang.app because of conflicts over the macOS menu, but for those only using Hyang command-line this will provide a much more intuitive interface to Tk for experienced Mac users. The configure on Hyang will be

--with-tcl-config=/Library/Frameworks/Tcl.framework/tclConfig.sh 
--with-tk-config=/Library/Frameworks/Tk.framework/tkConfig.sh

Use

library(tcltk)
tclvalue(.Tcl("tk windowingsystem"))  # "x11" or "aqua"

to find out which distribution of Tk is in use at run-time.


C.3.2 Java

Some binary distributions of Hyang may be built against a specific version of Java (e.g., 9). So the Hyang's command

$ sudo hyang CMD javareconf

will likely be needed before using Hyang's packages containing Java codes.

Compatible installed versions of Java will likely be checked by /usr/libexec/java_home -V -a x86_64. If needed, set the environment variable JAVA_HOME to choose between these, both when Hyang is built from the sources and when hyang CMD javareconf is run.

The Hyang build process will try to fathom out what JRE/JDK to use, but it may need some helps, e.g. by setting JAVA_HOME. A JDK will be specified explicitly by something like

JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home
JAVA_CPPFLAGS="-I/${JAVA_HOME}/include -I/${JAVA_HOME}/include/darwin"
JAVA_LD_LIBRARY_PATH="${JAVA_HOME}/lib/server"
JAVA_LIBS="-L/${JAVA_HOME}/lib/server -ljvm" 

or

JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_191.jdk/Contents/Home
JAVA_CPPFLAGS="-I/${JAVA_HOME}/include -I/${JAVA_HOME}/include/darwin"
JAVA_LD_LIBRARY_PATH="${JAVA_HOME}/jre/lib/server"
JAVA_LIBS="-L/${JAVA_HOME}/jre/lib/server -ljvm" 

in config.site file.

To use the builds of OpenJDK (tarballs) from http://jdk.java.net/, set the JAVA_HOME to be something like

JAVA_HOME=/path/to/JDK/jdk-11.jdk/Contents/Home

where /path/to/JDK is wherever the distribution tarball was unpacked. Setting the environment variable NOAWT to 1 will be necessary to install many of the Hyang packages containing Java codes.


C.3.3 Frameworks

The HYPA's build of Hyang will be installed as a framework, which will be selected by the option

$ ./configure --enable-hyang-fw

but it will only be needed if a build Hyang is with the hyang.app console, and this will imply the option --enable-hyang-shlib to build Hyang as a dynamic library. This option will configure Hyang to be built and installed as a framework, called hyang.fw. The default installation path for hyang.fw will be /Library/Frameworks but this can be changed at configure time by specifying the flag --enable-hyang-fw[=DIR] (or --prefix), or at install time via

$ make prefix=/where/you/want/hyang.fw/to/go install

Installing Hyang as a framework will be non-standard (particularly because it will take a non-standard location) and Unix-likes utilities may not support it (e.g. the pkg-config file libhyang.pc will be put somewhere unknown to pkg-config).


C.3.4 Building hyang.app

The hyang.app's GUI console will be built in a separate project, using Xcode. This will be a binary install. Before compiling hyang.app make sure the current version of Hyang is installed in /Library/Frameworks/hyang.fw and working at the command-line.

The hyang.app will not need to be installed in any specific way. The hyang.app builds will result in the hyang.app bundle which will appear as one Hyang icon. This application bundle will be run anywhere and it will be customary to place it in the /Applications folder.


Appendix D The Windows Toolset

Certain toolset versions 53 will be quite sensitive to the build process of Hyang. Certain add-on packages may somewhat more forgiving, but we recommend using the exact toolset at first.

Building Hyang and byte-compiled packages will need the following tools:

A complete build of Hyang including PDF manuals, and producing the installer will also need the following:

Set the PATH properly. The installers will optionally set the path to the components that it installs.


D.1 LaTeX

The pdftex may be available at the ‘MiKTeX’ (http://www.miktex.org/) distribution of LaTeX.

Please read The Hyang Manuals Designs about how to make fullrefman.pdf and set the environment variable HYANG_HYD4PDF suitably.


D.2 The Inno Setup Installer

The installer (e.g., hyang-1.3.0-win.exe) will require the Unicode version of Inno Setup 5.3.7 or later from http://jrsoftware.org/. Copy file src/hyangwin32/MkRules.dist to src/hyangwin32/MkRules.local and edit it to set ISDIR to the location where Inno Setup was installed.


D.3 The Command Line Tools

This will need suitable versions of at least make, cat, cp, mv, mkdir, echo, ls, du, touch, sh, cmp, rm, tar, zip, unzip, gzip, cut, uniq, sed, comm, makeinfo, sort, rsync, texindex, expr, diff, basename and date.

The environment variable CYGWIN will be used to values including ‘nodosfilewarning’ to suppress messages about paths.


Function and Variable Index

Jump to:   C   H   I   M   R   U  
Index Entry  Section

C
configure: Compilation Strategies
configure: Compilation Strategies
configure: The Hyang Installation Designs
configure: The Hyang Installation Designs
configure: Configuration variables
configure: Using make

H
HYANG_HOME: Compilation Strategies

I
install.packages: Installing packages

M
make: Using make

R
remove.packages: Removing packages

U
update.packages: Updating packages

Jump to:   C   H   I   M   R   U  

Concept Index

Jump to:   B   F   I   L   M   O   P   R   S   U   V   W  
Index Entry  Section

B
BLAS library: Linear algebra

F
FORTRAN: Using FORTRAN

I
Installation Designs: The Hyang Installation Designs
Installation under Unix-likes: Installation Strategies for Hyang 1.3.0 Under Unix-likes
Installation under Windows: Installation Strategies for Hyang 1.3.0 under Windows
Internationalization: Internationalization and Localization

L
LAPACK library: LAPACK
Libraries: Add-on packages
Libraries, managing: Managing libraries
Libraries, site: Managing libraries
Libraries, user: Managing libraries
Linux: Installation Strategies for Hyang 1.3.0 Under Unix-likes
Linux: Linux
Locale: Internationalization and Localization
Locale: Locales
Localization: Internationalization and Localization

M
macOS: Installation Strategies for Hyang 1.3.0 under macOS
macOS: macOS
Manuals: The Hyang Manuals Designs
Manuals, installing: The Hyang Installation Designs

O
On About This Document: On About This Document

P
Packages: The Hyang Add-on Packages
Packages, default: Default packages
Packages, installing: Installing packages
Packages, removing: Removing packages
Packages, updating: Updating packages

R
Repositories: Setting up a package repository

S
Site libraries: Managing libraries
Source for Document: Getting the Latest Version of This Document
Sourcing to Document: Using or Citing This Document

U
User libraries: Managing libraries

V
Vignettes: Required tools and libraries

W
winCairo.dll: Building the Cairo Devices files

Jump to:   B   F   I   L   M   O   P   R   S   U   V   W  

Environment Variable Index

Jump to:   B   C   D   H   J   L   P   T  
Index Entry  Section

B
BINPREF: Windows packages
BINPREF64: Windows packages
BLAS_LIBS: BLAS

C
CONFIG_SITE: Configuration variables
CYGWIN: The command line tools

D
DESTDIR: The hyangmath Libraries on Unix-likes

H
HYANG_ARCH: Sub-architectures
HYANG_ARCH: Sub-architectures
HYANG_BROWSER: Setting the browsers
HYANG_DEFAULT_PKGS: Default packages
HYANG_DISABLE_HTTPD: The Hyang Help Designs
HYANG_GSCMD: Other Useful tools and libraries
HYANG_INSTAR: Windows packages
HYANG_JAVA_LD_LIBRARY_PATH: Java support
HYANG_JAVA_LD_LIBRARY_PATH: Java support
HYANG_LIBS: The Hyang Add-on Packages
HYANG_LIBS_SITE: Managing libraries
HYANG_LIBS_USR: Managing libraries
HYANG_PPRSIZE: The Hyang Manuals Designs
HYANG_PPRSIZE: Setting paper size
HYANG_PPRSIZE: Making manuals
HYANG_PDFVIEWER: Setting the browsers
HYANG_HYD4PDF: The Hyang Manuals Designs
HYANG_HYD4PDF: Making manuals
HYANG_HYD4PDF: LaTeX
HYANG_SCRIPT_DEFAULT_PKGS: Default packages
HYANG_USER: Running Hyang

J
JAVA_HOME: Java support

L
LANG: Localization of Messages
LANGUAGE: Localization of Messages
LANGUAGE: Localization of Messages
LAPACK_LIBS: LAPACK
LC_ALL: Localization of Messages
LC_COLLATE: Testing strategies for Hyang 1.3.0 installation under Unix-likes
LC_MESSAGES: Localization of Messages
LD_LIBRARY_PATH: The hyangmath Libraries on Unix-likes
LD_LIBRARY_PATH: Using FORTRAN
LOCAL_SOFT: Windows Packages

P
PAPERSIZE: Setting paper size
PATH: Required tools and libraries
PATH: Using FORTRAN
PATH: The Windows Toolset

T
TAR: Essential programs and libraries
TEMP: Running Hyang
TMP: Running Hyang
TMPDIR: Compilation Strategies
TMPDIR: Building the Core Files
TMPDIR: Running Hyang
TMPDIR: Running Hyang
TMPDIR: Installing packages

Jump to:   B   C   D   H   J   L   P   T  

Footnotes

(1)

For instance :

Last Updated : 2019-04-18
Update History :
  • 2019-04-18 : Update a HYPA link
  • 2019-04-17 : Add a HYPA link

(2)

or send the email to each author's email address.

(3)

Their primary 64-bit library directories will be lib rather than using lib64.

(4)

The ‘inconsolata’ will be omitted (if not found by configure) on a Unix-like system.

(5)

This will be needed if more than one sub-architecture is to be installed.

(6)

with possible values ‘i386’, ‘x64’, ‘32’ and ‘64’.

(7)

How to prepare such a directory will be described at src/extra/tzone/Notes file in the Hyang sources.

(8)

for example, -fopenmp, -xopenmp or -qopenmp. This will include for clang, the Intel and Oracle compilers.

(9)

This will not necessarily disable the use of OpenMP. The Hyang's configure will allow for platforms where OpenMP is used without a flag. For the flang compiler in late 2017, the Fortran runtime always used OpenMP.

(10)

This will be a valid option for g++ 5 and later and 2016 versions of the Intel and Solaris compilers. For earlier versions of g++ one could try -std=c++1y.

(11)

This was true for earlier versions of g++ such as 4.2.1, and also for commonly-used versions of the Solaris CC compiler.

(12)

Currently only GCC and clang++ versions 6 and later.

(13)

For when features were supported, see https://gcc.gnu.org/projects/cxx-status.html#cxx11.

(14)

As the installer will put links to hyang and hyangscript in /usr/local/bin. If these are missing, run the copies directly in /Library/Frameworks/hyang.fw/Resources/.

(15)

The framework for Hyang will be named as org.hyang.hyang.mavericks.fw.pkg. Use the pkgutil --pkgs | grep org.hyang to check for earlier versions of Hyang.

(16)

unless they were excluded in the build.

(17)

its binding will be locked once the startup files have been read, so users will not easily change it.

(18)

See ?download.file if a proxy needs to be set.

(19)

The file such as etc/i386/Makevars.site can be used to place it, but will not be exist by default.

(20)

using a path containing spaces will likely cause problems.

(21)

They need to have been created using -headerpad_max_install_names, which will be default for a Hyang package.

(22)

The ‘X/Open Portability Guide’, which has had several versions.

(23)

also known as IEEE 754.

(24)

The on-FPU precision will be allowed to vary, at least when storing quantities.

(25)

e.g. beta, gamma and Bessel functions.

(26)

including selecting the architecture and copying MkRules.dist to MkRule.local.

(27)

also known as IEEE 754.

(28)

The C11 compilers will need not be C99-compliant. Hyang will require support for double complex and variable-length arrays which are optional in C11 but mandatory in C99.

(29)

For examples -std=gnu99, -std=c99 and -c99.

(30)

The -std=c99 will exclude POSIX functionality, but config.h will turn on all the GNU extensions to include the POSIX functionality, for Hyang itself. The default mode on recent GCC versions is -std=gnu11, which will include the optional features provided by Hyang.

(31)

The default behaviour of glibc can be changed by re-specifying the gconv modules to be loaded.

(32)

Particularly the C99 functionalities of

(33)

including log1p, expm1, va_copy, hypot, and nearbyint.

(34)

including opendir, readdir, closedir, popen, stat, glob, access, getcwd and chdir system calls, select on a Unix-alike, and either putenv or setenv.

(35)

such as symlink and realpath.

(36)

most often distributed as part of xz. Its names in Linux distributions might be xz-devel/xz-libs and liblzma-dev.

(37)

As from version 10.0 this will likely be known as PCRE1, and not PCRE2.

(38)

but not a major version greater than 7 should there ever be one.

(39)

such as to specify static linking with a build which has both shared and static libraries.

(40)

Such as GNU tar 1.15 or later, bsdtar or tar from the Heirloom Toolchest, although the latter does not support xz compression.

(41)

The texi2dvi will normally be a shell script. Some versions (including that from texinfo 5.2 and 6.0) will need to be run under bash rather than a Bourne shell (especially on Solaris). Some of the issues caused by the broken versions of texi2dvi will be circumvented by setting the environment variable HYANG_TEXI2DVICMD to the value emulation.

(42)

If necessary the path to pkg-config can be specified by setting PKGCONF in config.site file, on the configure command or in the environment.

(43)

also known as ttf-mscorefonts-installer in Debian.

(44)

also known as ttf-liberation in Debian.

(45)

This will be default, as from glibc 2.26.

(46)

Hyang will use rpc/xdr.h but that includes netconfig.h from the top tirpc directory.

(47)

This will be true even for the ‘Aqua’ version of Tk on macOS, but distributions of that will include a copy of the X11 files that needed.

(48)

The issue on macOS will be likely about the use of double-complex routines.

(49)

The measures will be likely about 15–20% on ‘i686’ Linux and around 10% on ‘x86_64’ Linux.

(50)

as well as its equivalence to the hyangcomplex structure defined in hyangexts/hyangcomplex.h.

(51)

This will be recommended, as it is a suitable implementation of clang on Apple.

(52)

Some of these will be unsigned packages.

(53)

Cygwin version of make 3.81 will be unsupported

 

 

 


Copyright (C) 2019 The Hyang Language Foundation, Jakarta. All rights reserved.