Docs Tutorial Contributing Licenses Gallery

Hyang 1.2.2 Installation and Usage

Copyright © 2017 Hyang Language Foundation, Jakarta. See the licenses notice.

Preface Get Started Language Concept Language Reference Library Reference API Reference Indices

1. Introduction

This part of documentation is devoted to basic information on the Hyang installation on different platforms, build Hyang from the sources, customization, the invocation of the Hyang interpreter and other things that may make working with Hyang easier or can enhance your productivity with the Hyang Language.

2. Get Prepared

Like many other programming languages, Hyang can run on a wide variety of platforms. Basically, there are two platform categories that are covered on the documentations here: Windows platforms (including Windows 95 and up) and Unix-type systems, including GNU/Linux, Mac OS X, AIX, BSD, and Solaris. Other operating systems and hardware platforms maybe capable of running Hyang, but are outside the scope of this documentation.

For the first of all things, you need the Hyang interpreter, named hyang.exe in Windows and hyang in Unix-types. In this part of documentations, we will use "Hyang" for the Hyang programming language or its implementations, and "hyang" for the Hyang interpreter.

The hyang is a cute program that enables you type Hyang commands and have them executed immediately (like calculator), or executes your Hyang scripts, either interactively or noninteractively. Next things, you will need additional tools such as a text editor and the abahyang compiler.

The abahyang is a standard C compiler that can turn a program written in this language into something that can run on your computer. With the C language on hand, Hyang can share syntactically with other software development kit written in any other programming languages that is compatible with the Hyang's application program interface (referred to as Hyang/C API).

3. Installing Hyang

To install Hyang, you can download a package either in source code (and build it yourself) or that has been compiled for the particular operating system platform. There are the advantages and disadvantages to each approach, as discussed in the following sections.

3.1. Build Hyang from The Sources

Hyang is mainly distributed in source code. You need to build it before using it. Hyang can be built on a wide variety of platforms with any ANSI-compliant C compiler, and compiles unmodified, and also compiles unmodified as C++.

The advantage is that all the Hyang libraries and hyang interpreter are compatible with the system on which it's built as long as it supports the tools and libraries needed to compile the source code — in Hyang's case, this is the abahyang with the standard C compiler — the resulting binary program is compatible with the platform.

There may any disadvantage of building Hyang from the source code, that the OS platform must have a complete C development environment that is generally not a problem on Unix/Unix-like platforms where such development are part of the established culture. But on Windows platforms, such a C compiler and its related tools are not installed by default. So you must install other suitable C compiler package for your Windows platforms, one of them is using TDM GCC which will be discussed later in this part of documentation.

3.1.1. On Unix-Type Variants

In most Unix/Unix-like platforms, you can simply use :

make

In a shell, move to the directory which is named hyang-1.2.2. The Makefile there controls both the build and the installation process. Use make followed by your platform. The currently supported platforms are: aix, bsd, c89, freebsd, generic, linux, macosx, mingw, posix, and solaris. If your platform is listed, just do:

make PLATFORM

where PLATFORM is is one of the name listed above. If your platform is not listed, try the closest one.

The compilation process take only a few minutes and create three files in the src directory: hyang (the interpreter), abahyang (the compiler), and libhyang.a (the library).

If you're running Linux and get compilation errors, make sure you have installed the readline development package (which is probably named libreadline-dev or readline-devel). If you get link errors after that, then try:

make linux MYLIBS=-ltermcap

After make completes, your shell prompt is displayed. If no error messages were encountered during the building process, you can test the Hyang interpreter by executing the following command:

make test

This will run the interpreter and print its version.

If you have root privileges on your system and would like hyang and abahyang to be available for other users, you should become root at this point and do this with the following command:

su –

Alternatively, you can use the sudo command to elevate your privilege level for particular commands. In this case, prefix the command requiring root authority with sudo. In general, using sudo requires some configuration using the visudo command. The hyphen tells the command that you want the root's environment, including its search paths, to be loaded. Doing so will likely change your default working directory, so you may need to return to the Hyang directory by using the cd command. For example:

cd /usr/local/src/hyang-1.2.2

Once you have built Hyang, you're now ready to install Hyang. You may want to install it in an official place in your system. In this case, do:

make install

The official place and the way to install files are defined in the Makefile. You'll probably need the right permissions to install files.

To build and install Hyang in one step, do :

make PLATFORM install

where PLATFORM is your platform name. To install Hyang locally, do:

make local

This will create a directory install, with subdirectories bin, include, lib, man, share, and install Hyang as listed below.

To install Hyang locally, but in some other directory, do:

make install INSTALL_TOP=dir

where dir is your chosen directory. The installation starts in the src and doc directories, so take care if INSTALL_TOP is not an absolute path.

bin:
    hyang abahyang

include:
    hyang.h hyangconfig.h hyanglib.h hyangextenlib.h hyang.hpp

lib:
    libhyang.a

man/man1:
    hyang.1 abahyang.1

These are the only directories you need for development. If you only want to run Hyang programs, you only need the files in bin and man. The files in include and lib are needed for embedding Hyang in C/C++ programs.

3.1.2. On Windows Variants

On Windows systems, you'll need to build the interpreter hyang.exe file, the compiler abahyang.exe file, and the library from the sources code package files as follows:

library:
    hyangapi.c hyangcode.c hyangctype.c hyangdebug.c hyangdo.c hyangdump.c 
    hyangfunc.c hyangpbc.c hyanglexical.c hyangmemory.c hyangobject.c 
    hyangopcodes.c hyangparser.c hyangstate.c hyangstring.c hyangworld.c 
    hyangtm.c hyangundump.c hyangvm.c hyangmios.c hyangextenlib.c hyangbaselib.c 
    hyangbitlib.c hyangcorolib.c hyangdblib.c hyangiolib.c hyangmathlib.c 
    hyangoslib.c hyangstrlib.c hyangworldlib.c hyangutf8lib.c hyangloadlib.c hyanginit.c

interpreter:
    library, hyang.c

compiler:
    library, abahyang.c

To use Hyang libraries in your own programs you'll need to make those libraries working with your compiler and to make sure that the Hyang/C API are accessible to those dynamic libraries — but don't link the Hyang library into each dynamic library. For Unix, we recommend that the Hyang library be linked statically into the host C program and its symbols exported for dynamic linking; src/Makefile does this for the Hyang interpreter. For Windows, we recommend that the Hyang library be a DLL. In all cases, the compiler abahyang should be linked statically.

A lot of C/C++ compilers exist for Windows, and many of them are available for free. For this section we will discuss using the Windows port using the open source GCC compiler by TDM. If you are an experienced programmer and find this too easy or limited, please use another method.

Step 1. Download TDM-GCC from this page. The downloaded file should be tdm-gcc-x.x.x.exe. We will assume you created the following folder as a working directory:

D:\hyang-install

Copy (or move) the tdm-gcc-x.x.x.exe file you just downloaded to the working directory, if you didn't download it there in the first place. Now our working directory should have the following content:

D:\hyang-install\tdm-gcc-x.x.x.exe

Step 2. Download Hyang source package from download page. Make sure that the file you download lies in the D:\hyang-install directory (or copy/move it there after the download complete). Now we have two files in our working directory:

D:\hyang-install\tdm-gcc-x.x.x.exe
D:\hyang-install\hyang-1.2.2.tar.gz

Step 3. Download a decompressor (7-Zip) for Hyang source package. The Hyang sources package is archived in TAR-GZ format as hinted by the .tar.gz double extension of the file. Windows platforms cannot decompress this format natively, so we need a program that can do that. A very good and versatile free decompression program for Windows that can handle TAR-GZ format (and many other compressed formats) is 7-zip. We will use the portable distribution of 7-zip package from this page. Click on the download link, follow the instructions and wait for the download to complete. Make sure that this file also lies in our working directory. Now we have three files in our working directory:

D:\hyang-install\tdm-gcc-x.x.x.exe
D:\hyang-install\hyang-1.2.2.tar.gz
D:\hyang-install\7-ZipPortable_x.x.paf.exe

Step 4. Install the TDM-GCC compiler. Execute the compiler's installer by double-clicking on tdm-gcc-x.x.x.exe. A dialog should appear:

  • Uncheck the option Check for updated files on the TDM-GCC server.
  • Press the button Create.
  • In the edit box that appear, specify D:\hyang-install\tdm-gcc as installation directory.
  • Press the button Next.
  • In the selection tree that appears scroll to the end and uncheck the options Start Menu Items and Add to PATH (this step is not strictly necessary, but it ensures that the compiler installation leaves the system completely clean, besides extracting the files into the directory specified above).
  • Press the button Install and wait for the installation to complete.
  • When the installer declares the installation successful, press the button Next.
  • Press the button Finish (you may read the readme file or not, it is not necessary for our purposes).

The current content of our working directory now should be:

D:\hyang-install\tdm-gcc-x.x.x.exe
D:\hyang-install\hyang-1.2.2.tar.gz
D:\hyang-install\7-ZipPortable_x.x.paf.exe
D:\hyang-install\tdm-gcc

with the last item being the subdirectory where the compiler is now installed.

Step 5. Now install the 7-zip portable by double-clicking on the file 7-ZipPortable_x.x.paf.exe inside our working directory. Specify D:\hyang-install\7zip as destination folder. The current content of our working directory now should be:

D:\hyang-install\tdm-gcc-x.x.x.exe
D:\hyang-install\hyang-1.2.2.tar.gz
D:\hyang-install\7-ZipPortable_x.x.paf.exe
D:\hyang-install\tdm-gcc
D:\hyang-install\7zip

with the last item being the subdirectory where 7-zip is now installed.

Step 6. Unpack Hyang sources package using 7-Zip. Browse into the 7-zip installation directory (i.e. D:\hyang-install\7zip) and double-click on the file 7-ZipPortable.exe. This will execute 7-zip and bring up the program's main window. Using 7-zip window, navigate to our working directory.

Inside 7-zip window, double-click on Hyang sources package file (i.e., hyang-1.2.2.tar.gz), you should see the content of the package as a single folder called hyang-1.2.2.tar. Double-click on hyang-1.2.2.tar, you should "enter" that folder and see another folder named hyang-1.2.2. Right-click on hyang-1.2.2, a context menu should appear. Select the Copy To... option from that menu. A dialog with a Copy caption should appear. Specify our working directory (i.e., D:\hyang-install) in that dialog as destination and press Ok. Close 7-zip window, we no longer need it.

Now browse into our working directory and check it: a new subdirectory named hyang-1.2.2 should be present.

The current content of our working directory now should be:

D:\hyang-install\tdm-gcc-x.x.x.exe
D:\hyang-install\hyang-1.2.2.tar.gz
D:\hyang-install\7-ZipPortable_x.x.paf.exe
D:\hyang-install\tdm-gcc
D:\hyang-install\7zip
D:\hyang-install\hyang-1.2.2

with the last item being the subdirectory where Hyang sources have been unpacked.

Step 7. Create a Windows shell script to drive the build using a text file named build.cmd in our working directory. Then copy and paste the following text inside it.

@echo off
:: ========================
:: file build.cmd
:: ========================
setlocal
:: you may change the following variable's value
:: to suit the downloaded version
set hyang_version=1.2.2

set work_dir=%~dp0
:: Removes trailing backslash
:: to enhance readability in the following steps
set work_dir=%work_dir:~0,-1%
set hyang_install_dir=%work_dir%\hyang
set compiler_bin_dir=%work_dir%\tdm-gcc\bin
set hyang_build_dir=%work_dir%\hyang-%hyang_version%
set path=%compiler_bin_dir%;%path%

cd /D %hyang_build_dir%
mingw32-make PLAT=mingw

echo.
echo **** COMPILATION TERMINATED ****
echo.
echo **** BUILDING BINARY DISTRIBUTION ****
echo.

:: create a clean "binary" installation
mkdir %hyang_install_dir%
mkdir %hyang_install_dir%\doc
mkdir %hyang_install_dir%\bin
mkdir %hyang_install_dir%\include

copy %hyang_build_dir%\doc\*.* %hyang_install_dir%\doc\*.*
copy %hyang_build_dir%\src\*.exe %hyang_install_dir%\bin\*.*
copy %hyang_build_dir%\src\*.dll %hyang_install_dir%\bin\*.*
copy %hyang_build_dir%\src\hyangconfig.h %hyang_install_dir%\include\*.*
copy %hyang_build_dir%\src\hyang.h %hyang_install_dir%\include\*.*
copy %hyang_build_dir%\src\hyanglib.h %hyang_install_dir%\include\*.*
copy %hyang_build_dir%\src\hyangextenlib.h %hyang_install_dir%\include\*.*
copy %hyang_build_dir%\src\hyang.hpp %hyang_install_dir%\include\*.*

echo.
echo **** BINARY DISTRIBUTION BUILT ****
echo.

%hyang_install_dir%\bin\hyang.exe -e"print[[Hello!]];print[[Hyang test successful!]]"

echo.

pause

The current content of our working directory now should be:

D:\hyang-install\tdm-gcc-x.x.x.exe
D:\hyang-install\hyang-1.2.2.tar.gz
D:\hyang-install\7-ZipPortable_x.x.paf.exe
D:\hyang-install\tdm-gcc
D:\hyang-install\7zip
D:\hyang-install\hyang-1.2.2
D:\hyang-install\build.cmd

Now run the shell script by double-clicking on build.cmd, a window with a black background should appear. Inside it you should see the messages produced by the script as it works (most of them are from GCC during the compilation of Hyang sources).

This can take a while, but it heavily depends on the performance of your PC. With our test system it took less than a minute. After the compilation has finished, the script will also create a "clean" binary distribution (i.e. without unnecessary source files) in our working directory and will perform a welcoming successfull test message before terminating.

**** BINARY DISTRIBUTION BUILT ****

Hello!
Hyang test successful!!!

Press any key to continue . . .

You should see that self-explanatory message at the end of the output in the black window. You can now close the black window by pressing any key.

The current content of our working directory now should be:

D:\hyang-install\tdm-gcc-x.x.x.exe
D:\hyang-install\hyang-1.2.2.tar.gz
D:\hyang-install\7-ZipPortable_x.x.paf.exe
D:\hyang-install\tdm-gcc
D:\hyang-install\7zip
D:\hyang-install\hyang-1.2.2
D:\hyang-install\build.cmd
D:\hyang-install\hyang

Step 8. The directory D:\hyang-install\hyang now contains everything is needed to run a Hyang script. You can copy this directory with its content wherever you may find convenient (even on a USB drive!).

In the bin subdirectory you will find:

  • hyang.exe, the Hyang interpreter (if you double-click on it, it will run in interactive mode)
  • The compiler abahyang.exe
  • The Library hyang12.dll

In the doc subdirectory you will find the Hyang manual:

  • hyang.1
  • abahyang.1

Whereas in the include subdirectory you will find:

  • hyang.h
  • hyang.hpp
  • hyangconfig.h
  • hyangextenlib.h
  • hyanglib.h

Step 9. Configure the system to run Hyang files. If you want to be able to type:

hyang myscript.hyang

to run myscript.hyang from the command line you must put the Hyang bin subdirectory on the Windows search path.

4. Customization

You may edit src/hyangconfig.h to customize some features before building Hyang.

Three kinds of things can be customized by editing a file:

  • Where and how to install Hyang — edit Makefile.
  • How to build Hyang — edit src/Makefile.
  • Hyang features — edit src/hyangconfig.h.

You don't actually need to edit the Makefile because you may set the relevant variables in the command line when invoking make. Nevertheless, it's probably best to edit and save the Makefile to record the changes you've made.

On the other hand, if you need to customize Hyang features, you can edit src/hyangconfig.h before building and installing Hyang. The edited file will be the one installed, and it will be used by any Hyang clients that you build, to ensure consistency. Further customization is available to experts by editing the Hyang sources.

5. Hyang Interpreter

An interpreter for Hyang as a standalone language, called simply hyang, is provided with the standard distribution. The standalone interpreter includes all standard libraries, including the debug library. Its usage is:

hyang [options] [script [args]]

The options are:

Commands Options
-e stat : Executes string stat.
-l mod : Set "requires" mod.
-i : Enters interactive mode after running script.
-v : Prints version information.
-E : Ignores environment variables.
-- : Stops handling options.
- : Executes stdin as a file and stops handling options.

After handling its options, hyang runs the given script. When called without arguments, hyang behaves as hyang -v -i when the standard input stdin is a terminal, and as hyang - otherwise.

When called without option -E, the interpreter checks for an environment variable HYANG_INIT_1_2 (or HYANG_INIT if the version name is not defined) before running any argument. If the variable content has the format @filename, then hyang executes the file. Otherwise, hyang executes the string itself.

When called with option -E, besides ignoring HYANG_INIT, hyang also ignores the values of HYANG_PATH and HYANG_CPATH, setting the values of package.path and package.cpath with the default paths defined in hyangconfig.h.

All options are handled in order, except -i and -E. For instance, an invocation like:

$ hyang -e'a=1' -e 'print(a)' myscript.hyang

will first set a to 1, then print the value of a, and finally run the file myscript.hyang with no arguments. Here $ is the shell prompt. Your prompt may be different.

Before running any code, hyang collects all global command-line arguments called arg. The script name goes to index 0, the first argument after the script name goes to index 1, and so on. Any arguments before the script name (that is, the interpreter name plus its options) go to negative indices. For instance, in the call:

$ hyang -la b.hyang w1 w2

the world is like this:

arg = { [-2] = "hyang", [-1] = "-la",
        [0] = "b.hyang",
        [1] = "w1", [2] = "w2" }

If there is no script in the call, the interpreter name goes to index 0, followed by the other arguments. For instance, the call:

$ hyang -e "print(arg[1])"

will print "-e". If there is a script, the script is called with parameters arg[1], ..., arg[#arg]. Like all niches in Hyang, the script is compiled as a vararg function.

In interactive mode, hyang repeatedly prompts and waits for a line. After reading a line, hyang first try to interpret the line as an expression. If it succeeds, it prints its value. Otherwise, it interprets the line as a statement. If you write an incomplete statement, the interpreter waits for its completion by issuing a different prompt.

If the global variable _PROMPT contains a string, then its value is used as the prompt. Similarly, if the global variable _PROMPT2 contains a string, its value is used as the secondary prompt (issued during incomplete statements).

In case of unprotected errors in the script, the interpreter reports the error to the standard error. If the error object is not a string but has a metamethod __tostring, the interpreter calls this metamethod to produce the final message. Otherwise, the interpreter converts the error object to a string and adds a stack traceback to it.

When finishing normally, the interpreter closes its main Hyang state (see hyang_close). The script can avoid this step by calling os.exit to terminate.

In order to use Hyang as a script interpreter in Unix systems, the standalone hyang skips the first line of a niche if it starts with #. Therefore, Hyang scripts can be made into executable programs by using chmod +x and the #! form, as in:

#!/usr/local/bin/hyang

Of course, the location of the Hyang interpreter may be different in your machine. If hyang is in your PATH, then:

#!/usr/bin/env hyang

is a more portable solution.

6. Working With Shell

We usually use the shell, also known as a command-line interface, to type commands to the computer. These commands can tell the computer to copy, move, delete, or to manipulate files, and to start programs, including (of course) Hyang programs and Hyang itself. In some cases, you’ll need to access your system's shell; in particular, everything that you need to type, you need to type into the shell. You can perform some of the operations, such as creating directories and moving files, using visual tools (such as Explorer on the Windows platform). Only the shell commands are presented here, but feel free to use whatever tools you are most comfortable with to accomplish the task at hand.

Usually, to access your shell on Windows, select Start, Run, type cmd, and press Enter. On Mac OS X, open your Applications folder (on your startup disk). Inside it, open the Utilities folder; inside that, open Terminal. On other systems with a graphical user interface (GUI), look in the menu that you start programs from for a program with a name like xterm, Konsole, or Terminal. On systems without a graphical user interface, you are already at the shell, as you are if you use a program such as ssh, telnet, or PuTTY to connect to a remote Unix(-like) server.

6.1. Shells Features

Shells presents some form of a prompt to let you know that it's waiting for you to issue a command. In general, you type a command following the prompt and press the Enter key to submit the command to the shell. When you are working in a shell, there is always one directory that is considered your current working directory. Most shell prompts contain that directory to make it easier for you to keep your bearings as you move from directory to directory. For example, a typical prompt in Windows shells may look something like the following:

C:\Program Files>

and in Unix-type shells, something like the following:

mozart maryann /usr/local/bin>

To exit the shell, type exit and press Enter.

6.2. The Environment

Each shell has the environment variables available to programs. The environment typically holds information about where the system should look for programs and libraries, what the shell prompt should look like, and so forth. You can view this information by issuing the following command at the shell prompt:

set

Regardless of the platform you use, you will want to modify the shell environment to let Hyang know where to find extension modules. Additionally, if you intend to compile Hyang or libraries, you'll need to set up environment variables that your SDK will look for.

On Unix-like systems, you generally modify the shell environment in one of the shell startup scripts. For example, if you use the bash shell, it will process /etc/bashrc and, in your home directory, .bashrc when it starts. The first file is used for system-wide settings, and the second is used for your own private settings. You'll need root privileges to modify the first. Within these files, you set an environment variable by including a line that looks like the following:

export HYANG_DIR=/usr/local/lib/hyang/1.2

When you reference environment variables in shell scripts, you precede the name with $, as in echo $HYANG_DIR.

The following environment variables are recommended for Unix-like systems:

HYANG_DIR=/usr/local/lib/hyang/1.2
HYANG_CPATH=?.so;$HYANG_DIR/?.so
HYANG_PATH=?.hyang;$HYANG_DIR/?.hyang

Restart the shell for changes to take effect.

Now create the actual directory that HYANG_DIR identifies. Do this, as root, with the following command:

mkdir -p /usr/local/lib/hyang/1.2

on Windows, depending on which version of Windows you use, you modify the shell environment either through the autoexec.bat file or through a dedicated dialog box that you get to through the System Properties dialog box. If you use autoexec.bat, you set environment variables with lines that look like the following:

SET HYANG_DIR="c:\program files\hyang\1.2"

If you use the dedicated dialog box, you'll need to choose between system variables and user variables. In this window, you can add a new variable, edit an existing variable, or delete an existing variable. When you add or edit a variable, there are separate input fields for the variable name and its value. Within a shell script, surround an environment variable name with the % character, as in — echo %HYANG_DIR%.

6.3. The Windows Search Path

On a Windows system, whether you compile Hyang or acquire a precompiled package, you'll want to put the Hyang interpreter, compiler, and dynamic link library in a location that makes them easy to use. From a shell prompt, the system should launch the interpreter when you execute the hyang command.

There are two practical approaches you can take: using aliases or using the search path. When you're at the shell prompt, Windows enables you to use a simple alias — hyang, for example — as a replacement for a more complicated command, such as C:\program files\utility\hyang.exe. It implements aliases like these, in addition to command-line editing and history, using doskey. This method may locate the aliased program slightly faster, but you cannot use the alias in a batch script. Consult the output of the following to read more about this utility:

doskey /?

You can also use the Windows search path mechanism. When a command is invoked that is not internal (such as dir or del) and is not qualified with path information, Windows examines the search path, looking for a matching executable. To see the current search path from the shell, execute this command:

path

In the following steps, you work with files and directories so you can use Windows Explorer if you like. Complete these steps to move the Hyang executables to a directory that is included in the Windows search path:

  1. If your current search path does not include a directory where you store utilities, create one now (the directory c:\program files\utility is assumed for this example, but the choice is yours). Note that quotes are necessary when specifying names with spaces:

    mkdir "C:\program files\utility"
  2. Add this directory to the Windows search path. On older versions of Windows, use the autoexec.bat file in the root directory of the boot drive. More recent versions of Windows still support this, but they also provide a graphical environment editor. If the text field containing the path variable is too small to see the entire value, cut and paste the value to your text editor, make the appropriate change, and then cut and paste the modified value back to the path edit field.
  3. The new search path applies only to shells that are opened after the change, so exit and restart your shell.

6.4. Settings for Windows

The following environment variables are recommended on Windows systems:

UTIL_DIR=C:\program files\utility
HYANG_DIR=C:\program files\hyang\1.2
HYANG_CPATH=?.dll;%HYANG_DIR%\?.dll
HYANG_PATH=?.hyang;%HYANG_DIR%\?.hyang

The UTIL_DIR variable identifies the utility directory you created in the preceding section. Additionally, if you have a software development kit and intend to compile Hyang and possibly libraries for Hyang, set the following environment variables:

SDK_DIR=C:\program files\msc
INCLUDE=%SDK_DIR%\include;%SDK_DIR%\include\usr
LIB=%SDK_DIR%\lib;%SDK_DIR%\lib\usr

The SDK_DIR depends on where you installed your SDK.

Restart the shell for environment changes to take effect. Then use Windows Explorer or the command shell to create the various directories that these environment variables identify.

7. Install Settings Tests

If you want to test the Hyang installation and settings you have just made on your OS, you need several tests to check out whether all of them have worked properly. For a reasonable test, we provide Hyang tests package that you can use to test your Hyang release. For Hyang 1.2.2, you can download tests package here, and follow the instructions below to run the tests. The tests for Hyang 1.2.2 work for later releases of Hyang 1.2. All Hyang test files are also distributed under the Hyang license.

7.1. Basic Tests

Decompress or extract the Hyang test package you just have downloaded somewhere in your directory. You'll see a directory named hyangtests-x.x.x containing several .hyang files and a few subdirectories.

To run some basic tests, go to this directory and run the following command:

path/hyang -e"_U=true" alltests.hyang

Make sure you run the exact release of Hyang that you wish to test. If you're in doubt, run hyang -v and check the output. If the release numbers do not match, you'll have to provide an explicit path.

The tests will print lots of different messages, but no postulation should ever fail. If the test goes all its way to the end, printing a "final OK" message, then all went well.

Note that, by its very nature, Hyang is heavily dependent on the underlying standard C libraries. Sometimes the test package fails because these underlying C libraries do not follow the ANSI standard. There is not much we can do about it.

7.2. Complete Tests

The test package uses some variables to control the execution of some tests. By defining the global variable _U (e.g., with the option -e"_U=true" in the command line as done for the basic tests above), the test package skip tests that are not fully portable and that consume too much memory. This option also suppresses messages for tests not performed. The basic tests should work without problems in any system with Hyang compiled without changes.

The complete test (that is, without the _U option) tries to test every corner of the language, its libraries, and the C API, even corners that are system dependent. Unlike Hyang itself, these tests do not aim at portability, small footprint, or easy of use. Their main goal is to try to crash Hyang. They are not intended for general use. You are welcome to use them, but expect to get your hands dirty.

To run the complete suite, first make sure that your test directory has subdirectories libs/ and libs/P1/, then go to subdirectory libs/ and build the C libraries there using the makefile provided (or its equivalent in your system). Now you may try to run the full test suite, by running the following command at the top-level test directory:

path/hyang alltests.hyang

Again, make sure you run the correct release of Hyang. Do not worry if it does not work the first time you try. (That is why there is the _U option after all.) You may need to adjust small details for your system. Among others, here is a list of things that may go wrong:

  • Small bugs in your system's C library;
  • File names returned by tmpnam cannot be opened or cannot be opened in write mode;
  • Names in C libraries need a "_" prefix (only for function package.loadlib; see test attrib.hyang);
  • Unconventional syntax for the command processor in os.execute.

7.3. Internal Tests

For even harder tests, the test suite uses a special library, testC, that gives access to several internal structures in Hyang. This library is only available when Hyang is compiled in debug mode, as described below.

If you want to run these internal tests, copy hyangtests.c and hyangtests.h from the hyangtests directory to the directory with the source Hyang files, and recompile Hyang with the option -DHYANG_USER_H='"hyangtests.h"' (or its equivalent to define HYANG_USER_H as the string "hyangtests.h", including the quotes). This option adds the testC library and enables several other internal tests as well. After the recompilation, run the tests as before. Again, expect to get your hands dirty.