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: https://github.com/HVML/hvml-docs.
• PurC (the Prime hVml inteRpreter for C language): https://github.com/HVML/PurC.
• xGUI Pro (an advanced HVML renderer based on WebKit): https://github.com/HVML/xGUI-Pro.
• HVML FPM (the FastCGI Process Manager for HVML): https://github.com/HVML/HVML-FPM.

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

• HybridOS Samples: https://github.com/HybridOS2/HBDSamples.

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:

https://hvml.fmsoft.cn/software

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 <path/to/the/root/of/the/source/tree/of/PurC>
$ 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 <path/to/the/root/of/the/source/tree/of/PurC>
$ 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 <path/to/the/root/of/the/source/tree/of/PurC>
$ 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:

<!DOCTYPE hvml>
<hvml target="void">

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

</hvml>

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 s