PurC

English 简体中文

PurC

PurC is the prime HVML interpreter for C/C++ language.

Table of Contents

• Introduction
• Release Status
• Building PurC
• Using purc
• Contributing
• Authors and Contributors
• Copying
• Tradmarks

Introduction

HVML is a descriptive programming language proposed and designed by [Vincent Wei], who is the author of [MiniGUI], one of the earliest open-source software projects in China.

PurC is the acronym of the Prime HVML inteRpreter for C/C++ language. It is also the abbreviation of Purring Cat, while Purring Cat is the nickname and the mascot of HVML.

The goal of PurC is to implement all features defined by [HVML Specification V1.0] and all predefined dynamic objects defined by [HVML Predefined Variables V1.0] in C language.

You can use PurC to run an HVML program or an HVML app by using the command line tool purc, or use PurC as a library to build your own HVML interpreter.

We release the PurC library under LGPLv3, so it is free for commercial use if you follow the conditions and terms of LGPLv3.

This is version 0.9.30 of PurC.

By now, PurC provides support for Linux and macOS. The support for Windows is on the way. We welcome anyone to port PurC to other platforms.

To learn the basic concepts of HVML programming, please refer to the following tutorials or articles:

• HVML, a Programable Markup Language
• Learn HVML Programming in 30 Minutes
• Embedding Python in HVML

For the Chinese version, please refer to the following links:

• 漫谈 HVML，它的由来和未来
• 30 分钟学会 HVML 编程
• 在 HVML 中嵌入 Python

For documents, specifications, and open-source software related to HVML, please refer to the following repositories:

• HVML Documents: .
• PurC (the Prime hVml inteRpreter for C language): .
• xGUI Pro (an advanced HVML renderer based on WebKit): .
• HVML FPM (the FastCGI Process Manager for HVML): .

For sample applications wrotten by using HVML, please refer to the following repository:

• HybridOS Samples: .

Release Status

Building PurC

Note that, if you are seeking the pre-built packages for platforms such as Ubuntu, Deepin, Homebrew, and MSYS2, you can refer to the following page:

Prerequisites

To build PurC from source code, please make sure that the following tools or libraries are available on your Linux or macOS system:

1. The cross-platform build system generator: CMake 3.15 or later
2. A C11 and CXX17 compliant compiler: GCC 8+ or Clang 6+
3. Zlib 1.2.0 or later
4. Glib 2.44.0 or later
5. BISON 3.0 or later
6. FLEX 2.6.4 or later
7. Python 3 (Python 3.9.0 or later if you want to build the external dynamic variant object $PY to use Python in HVML).
8. Ncurses 5.0 or later (optional; needed by Foil renderer in purc)
9. SQLite3 3.10.0 or later (optional)

If you want to enable the remote data fetcher, the following libraries are needed too:

1. libsoup2 or libsoup3
2. libgcrypt
3. libicu
4. libgpg-error
5. libunistring
6. openssl

If you are using Ubuntu 24.04 LTS or other similiar Linux distribution, you can use the following commands to install all above dependencies:

$ sudo apt install cmake gcc g++ bison flex python3
$ sudo apt install zlib1g-dev libglib2.0-dev libncurses-dev libbison-dev libpython3-dev libsqlite3-dev

# For remote fetcher:
$ sudo apt install libsoup-3.0-dev libgcrypt20-dev libgpg-error-dev libicu-dev libunistring-dev libssl-dev

Although the port for Windows is still on the way, it is possible to build PurC on Windows 10 version 2004 or later: You can install WSL (Windows Subsystem for Linux) and a Linux distribution, e.g., Ubuntu, on your Windows system, then build PurC in the Ubuntu environment.

Building steps

We assume that you are using Linux.

After fetching the source of PurC, you can change to the root of the source tree, and use the following command line to build and install PurC:

$ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DPORT=Linux -B build && cmake --build build && sudo cmake --install build

The above command line consists of the following commands:

1. cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DPORT=Linux -B build: Change to the build/ subdirectory and run cmake to generate the building files to build PurC. Note that this command uses the following options:
   • -DCMAKE_BUILD_TYPE=RelWithDebInfo: Specify the building type as RelWithDebInfo. You can also use Debug, Release, and other options supported by cmake.
   • -DPORT=Linux: Tell cmake that you are building PurC for an operating system based on the Linux kernel. Use -DPORT=Darwin if you are building PurC for macOS, iOS, or iPadOS.
   • -B build: Generate building files in the build/ subdirectory.
2. cmake --build build: Build PurC in the build/ subdirectory.
3. sudo cmake --install build: Install PurC from the build/ subdirectory.

You can also use the following commands to build and install PurC step by step:

$ cd 
$ rm -rf build/
$ mkdir build/
$ cd build/
$ cmake -DCMAKE_BUILD_TYPE=Release -DPORT=Linux ..
$ make -j4
$ sudo make install

If you'd like to use clang llvm instead of make to build PurC, you can use the following commands:

$ cd 
$ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DPORT=Linux -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang -Bbuild -GNinja &&  ninja -Cbuild && sudo ninja -Cbuild install

If you'd like to use ninja instead of make to build PurC, you can use the following commands:

$ cd 
$ cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DPORT=Linux -Bbuild -GNinja &&  ninja -Cbuild && sudo ninja -Cbuild install

Note that you might need to remove the build/ directory first if there is already one.

By default, the above commands will build PurC and install the headers, libraries, executables, and some documents to your system (under the /usr/local/ directory if you are using a Linux system).

When using make, you can use DESTDIR to specify an alternative installation directory:

$ make DESTDIR=/package/stage install

When using ninja, you can also use DESTDIR to specify an alternative installation directory:

$ DESTDIR="/package/stage" ninja -Cbuild install

Environment Variables

PurC uses the following environment variables for different purposes:

• PURC_DVOBJS_PATH: the path to save the shared modules for external dynamic objects.
• PURC_EXECUTOR_PATH: the path to save the shared modules for external executors.
• PURC_FETCHER_EXEC_PATH: the path to save the executable program of PurC Fetcher.
• PURC_USER_DIR_SUFFIX: The directory suffix for the user.
• PURC_LOG_ENABLE: true if enabling the global log facility.
• PURC_LOG_SYSLOG: true if enabling to use syslog as the log facility.

Using purc

The following sections assume that you have installed PurC to your system, and the command line tool purc has been installed into /usr/local/bin/. Make sure that you have added /usr/local/lib to /etc/ld.so.conf and run sudo ldconfig command, in order that the system can find the shared library of PurC you just installed into /usr/local/lib.

Run a single HVML program

Please save the following contents in a file named hello.hvml as your first HVML program in your working directory:

    $STREAM.stdout.writelines('Hello, world!')

To run this HVML program, you can use purc in the following way:

$ purc hello.hvml

You will see that your first HVML program prints Hello, world! on your terminal and quit:

Hello, world!

You can also run this HVML program directly as a script if you prepend the following line as the first line in your HVML program:

#!/usr/local/bin/purc

After this, run the following command to change the mode of the file to have the executing permission:

$ chmod +x hello.hvml

then run hello.hvml directly from the command line:

$ ./hello.hvml

Run a HVML program with errors or exceptions

Please save the following contents in a file named error.hvml in your working directory:

    $STREAM.stdout.writelines('Hello, world!)

We missed the second single quote of Hello, world! in the code above. The interpreter will exit with a nonzero return value if you run purc without any options:

$ purc error.hvml
$ echo $?
1

You can run purc with the option -v for a verbose message:

$ purc -v error.hvml
purc 0.9.30
Copyright (C) 2022 ~ 2025 FMSoft Technologies.
License GPLv3+: GNU GPL version 3 or later 
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Failed to parse HVML from file:///srv/devel/hvml/purc/build/error.hvml
HEE parse error: Unexpected unescaped control character
Source: file:///srv/devel/hvml/purc/build/error.hvml
Position: 3,46

    $STREAM.stdout.writelines('Hello, world!)
                                             ^
>>>>

This time, purc reported the error it encountered when it was parsing the HVML program: the wrong line and column (Position: 3,46).

If you change the program to add the missing single quote, purc will be happy to execute the HVML program.

For an uncaught runtime exception, purc will dump the executing stack.

For example, you can save the following program as exception.hvml:

    
        $STREAM.stdout.writelines("$0

This HVML program refers to an inexistent property (foo) of $CRTN.

Run purc to execute this HVML program with -v option, it will report the executing stack:

…

Assume you named the enhanced version as hello-10.hvml, we can run the program as two coroutines in parallel by specifying the command line flag -l:

$ purc -l hello-10.hvml hello-10.hvml

You will see the following output on your terminal:

…

In the above output, COROUTINE-3 and COROUTINE-4 contain the coroutine identifier assigned by PurC for two running instances of the program. You see that PurC schedules the running instances to execute alternately, i.e., in the manner of coroutines.

If you do not use the flag -l in the command line, purc will run the programs one by one:

…

Connecting to an HVML renderer

One of the important differences between HVML and other programming languages is that HVML can generate documents described in markup languages like HTML, not just output data to a file or your terminal.

For your convenience, we have prepared some HVML samples in the directory Source/Samples/hvml of this repository. After building PurC, the samples will be copied to the building root directory, under the hvml/ subdirectory, so that you can change to the building root directory and use purc to run the samples. For example:

$ cd 
$ purc hvml/fibonacci-void-temp.hvml

This HVML program will output 18 Fibonacci numbers less than 2000. There is also another version of this program: hvml/fibonacci-html-temp.hvml. It will generate an HTML document listing the Fibonacci numbers.

If you run hvml/fibonacci-html-temp.hvml program by using purc without any option, purc will use the renderer called