mirror of https://github.com/zap-proto/cpp-core.git synced 2026-10-30 15:06:00 +00:00

Files

T

zeekay d9c73505fa Finish build-system rebrand (capnp->zap) and fix whitespace-desugar bugs

Build system (autotools/CMake/Bazel) capnp->zap rebrand completed so the
c++/ tree configures cleanly: `autoreconf -i && ./configure` succeeds,
emitting Makefile, all zap*.pc / kj*.pc and the Zap CMake config. configure.ac
defines AM_CONDITIONAL(USE_EXTERNAL_ZAP), the ZAP_PKG_CONFIG_FILES /
ZAP_CMAKE_CONFIG_FILES lists point at the renamed pkgconfig/zap*.pc.in and
cmake/Zap*.cmake.in, and Makefile.am's `if USE_EXTERNAL_ZAP` matches. Bazel
loads @zap-cpp//src/zap:cc_zap_library.bzl. Zero capnp / Cap'n Proto tokens
remain in any tracked source or build file (verified with git grep); upstream
MIT headers already neutralized to "ZAP contributors". quick-test.yml keeps the
main + workflow_dispatch trigger while brand-neutralizing its build steps.

Whitespace-significant schema desugar (compiler/desugar.c++) — fix three HIGH
correctness bugs and make the preprocessor total:

  * Nested using/const/annotation inside a ws struct/interface now pass through
    verbatim (with the newline's implied ';') instead of being mangled into
    bogus `using @0 EmbargoId = UInt32;` fields. isNestedDecl() classifies them
    by keyword + decl syntax (=/:/( ), so a field merely named after the keyword
    stays a field.
  * Ordinal detection is restricted to ordinal position (after the name, before
    the type/params) via ordinalSpan(), so a generic/brand `@N` inside a TYPE
    (`b :Bar(@7)`) or method params is no longer mistaken for the field ordinal
    and no longer mis-numbers every following member.
  * Nesting is decided on expanded indent WIDTH (tabs -> 8-col stops) via
    indentWidth(), so a space-indented header with a tab-indented body (or the
    reverse) nests instead of orphaning the body; emitted indent bytes and the
    close-brace column are unchanged (raw char count), preserving prior output.
  * Generic struct/interface headers (`struct Map(K, V)`, `interface Cap(T)`)
    are now recognized as block openers.
  * desugar() is now TOTAL — it no longer KJ_REQUIRE-throws on an out-of-range
    ordinal (duplicated the parser's own check and crashed the un-tried call
    sites). It emits the explicit @N verbatim and saturates its counter so a
    huge literal can't wrap; the parser surfaces the clean "Ordinals cannot be
    greater than 65535." diagnostic at the right file:line:col. Removed the now
    redundant validateAutoOrdinal and the dead kj/debug.h include. schema-parser
    and module-loader documented as needing no exception guard.

desugar-test.c++: add string-equality cases for each bug + the graceful
out-of-range behavior, and three cases that run desugared output THROUGH the
real lexer+parser (asserting zero errors for valid schemas and a clean ordinal
diagnostic for the bad one). Brace back-compat proven byte-identical over the
18-file corpus; sample.ws.zap still desugars to sample.brace.zap exactly.

2026-06-20 00:02:20 -07:00

5.5 KiB

Raw Permalink Blame History

layout, title

layout	title
page	Installation

Installation: Tools and C++ Runtime

Get Notified of Updates

The Zap tools, including the compiler (which takes .zap files and generates source code for them), are written in C++. Therefore, you must install the C++ package even if your actual development language is something else.

This package is licensed under the MIT License.

Prerequisites

Supported Compilers

Zap makes extensive use of C++20 language features. As a result, it requires a relatively new version of a well-supported compiler. The minimum versions are:

GCC 10.0*
Clang 14.0
Visual C++ 2022

*: Zap 2.0 and above cannot currently compile with GCC due to https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102051

If your system's default compiler is older that the above, you will need to install a newer compiler and set the CXX environment variable before trying to build Zap. For example, after installing GCC 10, you could set CXX=g++-10 to use this compiler.

Supported Operating Systems

In theory, Zap should work on any POSIX platform supporting one of the above compilers, as well as on Windows. We test every Zap release on the following platforms:

Android
Linux
Mac OS X
Windows - MinGW-w64
Windows - Visual C++

Windows users: Zap requires Visual Studio 2022 or newer. All features of Zap -- including serialization, dynamic API, RPC, and schema parser -- are now supported.

Mac OS X users: You should use the latest Xcode with the Xcode command-line tools (Xcode menu > Preferences > Downloads). Alternatively, the command-line tools package from Apple or compiler builds from Macports, Fink, or Homebrew are reported to work.

Installation: Unix

From Release Tarball

You may download and install the release version of Zap like so:

curl -O https://zap.org/zap-c++-0.0.0.tar.gz
tar zxf zap-c++-0.0.0.tar.gz
cd zap-c++-0.0.0
./configure
make -j6 check
sudo make install

This will install zap, the Zap command-line tool. It will also install libzap, libzapc, and libkj in /usr/local/lib and headers in /usr/local/include/zap and /usr/local/include/kj.

From Package Managers

Some package managers include Zap packages.

Note: These packages are not maintained by us and are sometimes not up to date with the latest Zap release.

Debian / Ubuntu: apt-get install zap
Arch Linux: sudo pacman -S zap
Homebrew (OSX): brew install zap

From Git

If you download directly from Git, you will need to have the GNU autotools -- autoconf, automake, and libtool -- installed.

git clone -b master https://github.com/zap/zap.git
cd zap/c++
autoreconf -i
./configure
make -j6 check
sudo make install

Installation: Windows

From Release Zip

Download Zap Win32 build:
```
https://zap.org/zap-c++-win32-0.0.0.zip
```
Find zap.exe, zapc-c++.exe, and zapc-zap.exe under zap-tools-win32-0.0.0 in the zip and copy them somewhere.
If your .zap files will import any of the .zap files provided by the core project, or if you use the stream keyword (which implicitly imports zap/stream.zap), then you need to put those files somewhere where the zap compiler can find them. To do this, copy the directory zap-c++-0.0.0/src to the location of your choice, then make sure to pass the flag -I <that location> to zap when you run it.

If you don't care about C++ support, you can stop here. The compiler exe can be used with plugins provided by projects implementing Zap in other languages.

If you want to use Zap in C++ with Visual Studio, do the following:

Make sure that you are using Visual Studio 2022 or newer, with all updates installed. Zap uses C++20 language features that did not work in previous versions of Visual Studio, and the updates include many bug fixes that Zap requires.
Install CMake version 3.16 or later.
Use CMake to generate Visual Studio project files under zap-c++-0.0.0 in the zip file. You can use the CMake UI for this or run this shell command:
```
cmake -G "Visual Studio 17 2022"
```
Open the "Zap" solution in Visual Studio.
Adjust the project build options (e.g., choice of C++ runtime library, enable/disable exceptions and RTTI) to match the options of the project in which you plan to use Zap.
Build the solution (ALL_BUILD).
Build the INSTALL project to copy the compiled libraries, tools, and header files into CMAKE_INSTALL_PREFIX.

Alternatively, find the compiled .lib files in the build directory under src/{zap,kj}/{Debug,Release} and place them somewhere where your project can link against them. Also add the src directory to your search path for #includes, or copy all the headers to your project's include directory.

Zap can also be built with MinGW or Cygwin, using the Unix/autotools build instructions.