chaiscript-stdlib

ChaiScript is a header-only C++ embedded scripting language loosely based on ECMA script. It is designed for ease of use and tight integration with C++.

Usage

The original ChaiScript repository has been split into multiple build2 packages to allow for greater flexibility. The libchaiscript package is used to get access to the ChaiScript header-only library. The package chaiscript makes ChaiScript's own interpreter chai available to be used. chaiscript-stdlib exports the compiled and dynamically loadable standard library module for the basic ChaiScript engine. Typically, you will not need to use this one.

Make sure to add the or alpha or stable section of the cppget.org repository to your project's repositories.manifest to be able to fetch the packages.

:
role: prerequisite
location: https://pkg.cppget.org/1/stable
# trust: ...

If the cppget.org repository is not an option then add this Git repository itself instead as a prerequisite.

:
role: prerequisite
location: https://github.com/build2-packaging/chaiscript.git

Add the respective dependencies in your project's manifest file to make the packages available for import. Hereby, all packages should use the same version constraint.

depends: libchaiscript ^ 6.1.0
# or
depends: { libchaiscript chaiscript chaiscript-stdlib } ^ 6.1.0

The header-only C++ library to use ChaiScript as an embedded language can be imported by the following declaration in a buildfile.

import chaiscript = libchaiscript%lib{chaiscript}

Using the chai interpreter for ChaiScript scripts, as a REPL, or as build-time dependency with immediate and standard importation is supported. Because it is not able to change the code of chai, there is no way for now to provide any metadata in the executable.

import chai = chaiscript%exe{chai}
# or
import! chai = chaiscript%exe{chai}

To import the dynamically loadable module which provides the standard library for a ChaiScript instance, we need to rely on metadata. A dynamic module should not be linked to your executable but instead loaded at runtime. Hence, to use it properly for running ChaiScript scripts for tests or other things, you would need the module as a prerequisite but only use its directory as input. This can be accomplished by immediate importation with metadata support.

import! [metadata, rule_hint=cxx.link] \
    stdlib_module = chaiscript-stdlib%libs{chaiscript_stdlib}
stdlib_dir = [dir_path] $($stdlib_module: chaiscript_stdlib.dir)

Configuration

Multithread Support

Multithread support is enabled by default and may be turned off by using the following configuration variable. On Unix-based targets, pthread will be linked when enabled.

config [bool] config.libchaiscript.multithread_support_enabled ?= true

Dynamic Module Loading

The support to dynamically load ChaiScript modules is enabled by default and may be turned off by using the following configuration variable.

config [bool] config.libchaiscript.dynload_enabled ?= true

Use of GNU readline

For now, the use of the GNU readline library for the ChaiScript interpreter chai is disabled by default to allow for out-of-the-box CI builds.

If readline is available on the system, we recommend to enable it.

config [bool] config.chaiscript.use_readline ?= false

Issues and Notes

• Supported Platforms:
  • Linux: GCC, Clang but not withlibc++
  • Windows: MSVC, GCC, and Clang
  • MacOS: chaiscript-stdlib is not supported

• ChaiScript is not made for C++20 and higher language standards. As the library is header-only, we do not restrict the language standard of the library package libchaiscript but instead keep it to be cxx.std = latest. Especially when using Clang, this may result in compilation errors in a project that uses ChaiScript, such as it has been with its own samples and tests. For now, the workaround is to force the C++17 standard with cxx.std = 17. If this is not an option, this package will probably not work with your project.
• Using Clang on Windows with MSVC, the object copy count test given in the compiled_tests.cpp file fails due to the wrong number of destructor and move calls. This is most likely an implementation issue of ChaiScript and, looking into the up-to-date develop branch, fixed in the prerelease of version 7.0.0.
• This package does not build or execute the fuzzer test.
• This package does not build or execute the performance tests because valgrind would be needed.
• Not all unit tests based on ChaiScript scripts are sucessfull when using Clang with libc++. This seems to be an implementation issue of the ChaiScript library itself.
• To fix the strange inclusion scheme of the statically generated libraries parser and stdlib, their content actually needed to be copied and adjusted.
• If there would ever be a new version, check against new script files for testing and adjust all the symbolic links.

Contributing

Thanks in advance for your help and contribution to keep this package up-to-date. For now, please, file an issue on GitHub for everything that is not described below.

Recommend Updating Version

Please, file an issue on GitHub with the new recommended version.

Update Version by Pull Request

1. Fork the repository on GitHub and clone it to your local machine.
2. Run git submodule init and git submodule update to get the current upstream directory.
3. Inside the upstream directory, checkout the new library version X.Y.Z by calling git checkout vX.Y.Z that you want to be packaged.
4. If needed, change source files, buildfiles, and symbolic links accordingly to create a working build2 package. Make sure not to directly depend on the upstream directory inside the build system but use symbolic links instead.
5. Test if the packages compile and execute examples and tools.
6. Update library version in all manifest files if it has changed or add package update by using +n for the n-th update.
7. Make an appropriate commit message by using imperative mood and a capital letter at the start and push the new commit to the master branch.
8. Run bdep ci and test for errors.
9. If everything works fine, make a pull request on GitHub and write down the bdep ci link to your CI tests.
10. After a successful pull request, we will run the appropriate commands to publish a new package version.

Update Version Directly if You Have Permissions

1. Inside the upstream directory, checkout the new library version X.Y.Z by calling git checkout vX.Y.Z that you want to be packaged.
2. If needed, change source files, buildfiles, and symbolic links accordingly to create a working build2 package. Make sure not to directly depend on the upstream directory inside the build system but use symbolic links instead.
3. Test if the packages compile and execute examples and tools.
4. Update library version in all manifest files if it has changed or add package update by using +n for the n-th update.
5. Make an appropriate commit message by using imperative mood and a capital letter at the start and push the new commit to the master branch.
6. Run bdep ci and test for errors and warnings.
7. When successful, run bdep release --tag --push to push new tag version to repository.
8. Run bdep publish to publish the package to cppget.org.