Spire.Doc.Cpp 14.9.13

Spire.Doc for C++ (native)

A native C++ Word library. No Microsoft Office and no .NET runtime required on the target machine. Ships two entry points: a C++ API (Spire/Doc/**.h) and a pure C API (Spire.Doc.C.h).

64-bit only — there is no 32-bit build.

1. Quick start — C++ API

#include "Spire/Doc/Document.h"
#include "Spire/Doc/Section.h"
#include "Spire/Doc/Documents/Paragraph.h"
#include "Spire/Doc/Fields/TextRange.h"

using namespace Spire::Doc;
using namespace Spire::Doc::Documents;   // Paragraph lives here since 14.9.x

int main() {
    intrusive_ptr<Document>  document  = new Document();
    intrusive_ptr<Section>   section   = document->AddSection();
    intrusive_ptr<Paragraph> paragraph = section->AddParagraph();

    paragraph->AppendText("Hello World!");          // narrow char since 14.9.x
    document->SaveToFile("HelloWorld.docx", FileFormat::Docx);
    document->Close();
    return 0;
}

In a .vcxproj that consumed this package nothing else is needed — the import library, the include directories and the four runtime DLLs are wired up by the package's build/native/Spire.DOC.Cpp.targets.

Building from a plain command line instead:

clang++ -std=c++14 -I "<PKG>/include" -I "<PKG>/include/Spire/Doc" ^
    -I "<PKG>/include/Spire/Doc/common/h" demo.cpp ^
    -L "<PKG>/lib/win-x64" -lSpireDocCpp -o demo.exe

2. Quick start — pure C API

Spire.Doc.C.h is self-contained: it needs one include directory, has no dependency on windows.h, and passes only const char* / int* across the ABI, so it is immune to the character-set and C-runtime pitfalls described in section 4.

#include "Spire.Doc.C.h"

int* err  = 0;
int* doc  = Document_CreateDocumentV(&err);
int* sec  = Document_AddSection(doc, &err);
int* para = Section_AddParagraph(sec, &err);

Paragraph_AppendText(para, "Hello World from the C API!", &err);
Document_SaveToFileFF(doc, "C_HelloWorld.docx", 10 /* Docx */, &err);
Document_Close(doc, &err);
Spire_FreeAllAllocated();

cl c_hello.c /I "<PKG>\include" /link "<PKG>\lib\win-x64\Spire.Doc.Base.lib"

On Linux the C API is the only entry point that currently works — see section 4.

3. Package layout

include/
  Spire.Doc.C.h          pure C API header - recommended for new C projects
  Spire.Doc.o.h          umbrella header (compatibility shim, see below)
  Spire/Doc/**.h         C++ API, namespaces mirror .NET (Spire::Doc::Document, ...)
lib/<platform-id>/       native libraries, pick the directory for your platform
build/native/            MSBuild integration (Spire.DOC.Cpp.targets) + license
docs/                    Readme-CN.txt, Readme-EN.txt, ReleaseNotes.md

Platform ids in this package: win-x64, win-arm64, linux-x64, linux-arm64. Other platforms (linux-musl-, ohos-, osx-*) are only in the ZIP distribution.

4. Settings this package handles for you

Earlier 14.9.x packages required the consumer to change project settings by hand. This build does it for you — a plain Visual Studio wizard project, including a default Debug|x64 configuration, builds and runs as-is. What is involved, in case you need to opt out:

Spire.Doc.o.h (the umbrella header present up to 14.7.2 and dropped in 14.9.x) is restored as a shim, so legacy #include "Spire.Doc.o.h" code still compiles.

5. Platform notes

Windows — win-x64 and win-arm64 are both fully wired up. Compile with C++11 or C++14; do not use C++17 (a byte typedef in the wrapper headers clashes with std::byte).

Linux — libSpireDocCpp.so is cross-built against libc++ (std::__1) while mainstream Linux C++ compilers use libstdc++ (std::__cxx11). Every std::string crossing the C++ ABI is therefore read as garbage: the output file name comes out as random bytes and the body text is garbled. This is a regression introduced in 14.9.0 — 14.7.2 was built against libstdc++. Use the C API on Linux until the library is rebuilt. linux-arm64 additionally needs libicu; setting DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 works around its absence.

6. Runtime library location

The executable must be able to find the native libraries at run time. Under MSBuild the package copies them next to the output for you. Otherwise, copy everything from lib/<platform-id>/ next to your executable, or put that directory on PATH (LD_LIBRARY_PATH on Linux).

中文说明

Spire.Doc for C++ 是一个原生 C++ Word 文档库，同时提供 C++ API（Spire/Doc/**.h） 与纯 C 接口（Spire.Doc.C.h）。不依赖 Microsoft Word / Office，目标机器上也无需 .NET 运行时。仅提供 64 位版本。

快速开始（C++ API）

#include "Spire/Doc/Document.h"
#include "Spire/Doc/Section.h"
#include "Spire/Doc/Documents/Paragraph.h"
#include "Spire/Doc/Fields/TextRange.h"

using namespace Spire::Doc;
using namespace Spire::Doc::Documents;   // 14.9.x 起 Paragraph 在此命名空间

int main() {
    intrusive_ptr<Document>  document  = new Document();
    intrusive_ptr<Section>   section   = document->AddSection();
    intrusive_ptr<Paragraph> paragraph = section->AddParagraph();

    paragraph->AppendText("Hello World!");          // 14.9.x 起为窄字符
    document->SaveToFile("HelloWorld.docx", FileFormat::Docx);
    document->Close();
    return 0;
}

以 NuGet 方式引入本包后，不需要再改任何工程设置 —— 导入库、include 路径和 四个运行时 DLL 都由包内的 build/native/Spire.DOC.Cpp.targets 自动配置， 包括 VS 向导默认的 Debug|x64 配置。

快速开始（纯 C 接口）

Spire.Doc.C.h 自包含，只需一个 include 目录；它不引用 windows.h，跨 ABI 的 只有 const char* 和 int*，因此不受字符集和 C 运行时问题影响（见下）。 Linux 上目前只有 C 接口可用。

#include "Spire.Doc.C.h"

int* err  = 0;
int* doc  = Document_CreateDocumentV(&err);
int* sec  = Document_AddSection(doc, &err);
int* para = Section_AddParagraph(sec, &err);

Paragraph_AppendText(para, "Hello World from the C API!", &err);
Document_SaveToFileFF(doc, "C_HelloWorld.docx", 10 /* Docx */, &err);
Document_Close(doc, &err);
Spire_FreeAllAllocated();

cl c_hello.c /I "<PKG>\include" /link "<PKG>\lib\win-x64\Spire.Doc.Base.lib"

本包替你处理的三件事

以前的 14.9.x 包要求用户手工改工程设置，本包已自动化，向导默认工程（含默认 Debug|x64）开箱即可编译运行：

另外恢复了 14.7.2 之后被删掉的伞头文件 Spire.Doc.o.h（兼容层，只含常用头）， 老代码里的 #include "Spire.Doc.o.h" 仍可编译。

平台说明

• Windows：win-x64 与 win-arm64 都已配置完整。请用 C++11/C++14，不要用 C++17 （包装头里的 byte typedef 与 std::byte 冲突）。
• Linux：libSpireDocCpp.so 是用 libc++（std::__1）交叉编译的，而 Linux 上常规 编译器用 libstdc++（std::__cxx11），跨 C++ ABI 的 std::string 全部读成垃圾 —— 表现为生成的文件名是随机字节、正文乱码。这是 14.9.0 引入的回归（14.7.2 还是 libstdc++）。在重新构建 .so 之前，Linux 上请使用 C 接口。 linux-arm64 还需要 libicu，没有时可设 DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1。

运行时库位置

可执行文件必须能找到原生库。通过 MSBuild 构建时包会自动把它们复制到输出目录； 其它方式请把 lib/<平台>/ 下的文件放到可执行文件同目录，或把该目录加入 PATH （Linux 为 LD_LIBRARY_PATH）。