3-1. Setup WebCFace Library

Table of Contents

• C/C++
  • API
  • C++20 modules
• Python
• JavaScript/TypeScript

以降、このドキュメントではクライアントの仕様変更された機能は
C,C++のwebcface:
webcface-js:
webcface-python:
の画像で示します。

C/C++

C/C++のライブラリはREADMEにしたがってwebcfaceをインストールすれば使うことができます。 MesonまたはCMakeを使用する場合は、subproject/subdirectoryとしてWebCFaceを追加してソースからビルドすることもできます。

• Meson

  Since

  2.0

  インストールしたWebCFaceを使用する場合の例

  webcface_dep = dependency('webcface', version: '>=2.0.0')

  • webcfaceはpkg-configのファイル(lib/pkgconfig/webcface.pc)とcmakeのファイル(lib/cmake/webcfaceConfig.cmake)の両方をインストールし、どちらもMesonから読み込むことができます。
  • pkg-configで読み込む場合は環境変数PKG_CONFIG_PATH(またはmesonの引数-Dpkg_config_path)に (webcfaceのパス)/lib/pkgconfig を追加する必要があります。
  • cmakeで読み込む場合は環境変数PATHに (webcfaceのパス)/bin を追加するか、 mesonの引数-Dcmake_prefix_pathにwebcfaceのパスを追加する必要があります。
  • パッケージ名はどちらも小文字でwebcfaceです。

  subprojectにする場合は以下のようなwrapを書き、

  [wrap-git]
  url = https://github.com/na-trium-144/webcface.git
  revision = v3.2.0
  depth = 1
  [provide]
  dependency_names = webcface

  インストールしたWebCFaceを使う場合と同様にdependency()で使用することができます。 またはwebcfaceのgitリポジトリ(https://github.com/na-trium-144/webcface.git )を直接subproject/ディレクトリに置いても使えると思います。

  Note

  • C++でWebCFaceを使用するにはC++17が必要です。 mesonの引数で -Dcpp_std=c++17 のように指定するか、 project() に ‘default_options: ['cpp_std=c++17’],` のように記述するとよいです。
  • staticビルドにしたり、webcface-serverのビルドの有無を切り替えたりといったオプションについては 3-2. Building from source を参照

• CMake インストールしたWebCFaceを使用する場合の例

  find_package(webcface 2.0 CONFIG REQUIRED)
   
  target_link_libraries(your-target PRIVATE webcface::webcface) # C++の場合
  target_link_libraries(your-target PRIVATE webcface::wcf) # Cの場合(ver1.5.1〜)

  • find_packageでwebcfaceが見つからない場合は環境変数PATHに (webcfaceのパス)/bin を追加するか、 webcfaceのインストール場所をCMAKE_PREFIX_PATHかwebcface_ROOT, webcface_DIRなどに設定してください。

  Note

  webcface::webcface ターゲットには cpp_std_17 が、 webcface::wcf ターゲットには c_std_99 の指定がそれぞれ含まれています。

  FetchContentを使う場合

  FetchContent_Declare(webcface
    GIT_REPOSITORY https://github.com/na-trium-144/webcface.git
    GIT_TAG        v3.2.0
  )
  FetchContent_MakeAvailable(webcface)

  またはwebcfaceのgitリポジトリ(https://github.com/na-trium-144/webcface.git )を直接どこかのディレクトリに置いてadd_subdirectory()でも使えると思います。

  Warning

  2.0 WebCFaceのリポジトリにはCMakeLists.txtがありますが、中身はcustom_targetでmesonを呼び出す仕様になっています。 そのためFetchContentやsubdirectoryとしてWebCFaceをソースからビルドする場合はMeson(ver1.3以上)のインストールが必要になります。

  • Linux: sudo apt install meson(ubuntu24.04以降) または pip install meson
  • MacOS: brew install meson または pip install meson
  • Windows: https://github.com/mesonbuild/meson/releases からmsi形式でダウンロード、インストール

• pkg-config 環境変数PKG_CONFIG_PATHに (webcfaceのパス)/lib/pkgconfig を追加し、

  • コンパイル時の引数に $(pkg-config --cflags webcface)
  • リンク時に $(pkg-config --libs webcface)

  を渡せばよいです

• 手動リンク
  • インクルードディレクトリ(-I など): (webcfaceのパス)\include
  • ライブラリディレクトリ(-L など): (webcfaceのパス)\lib
  • Linux, MacOS
    • -lwebcface でリンクできるはずです。
  • Windows (MSVC)
    • リンクするライブラリは、 webcface.lib (Release) / webcfaced.lib (Debug)
    • また、(webcfaceのパス)\bin を環境変数のPathに追加するか、 その中にある webcface-20.dll / webcfaced-20.dll ファイルを実行ファイルのディレクトリにコピーして読み込ませてください

API

C++のソースコードでは<webcface/webcface.h>をincludeするとwebcfaceのすべての機能が使用できます。

1.10 <webcface/client.h>, <webcface/value.h>など必要なヘッダファイルだけincludeして使うこともでき、コンパイル時間を短縮できます。

1.5 C++ではなくCからアクセスできるAPIとして、wcf〜 で始まる名前の関数やstructが用意されています。 (C++ライブラリのうちの一部の機能しかまだ実装していませんが)

<webcface/c_wcf.h> をincludeすることで使えます。
1.7 <webcface/wcf.h> をincludeすることで使えます。(c_wcf.hも一応使えます)
ほとんどの関数は戻り値が int 型 2.0 enum wcfStatus 型で、 成功した場合 0 (= WCF_OK)、例外が発生した場合正の値を返します。

C++20 modules

Since

3.0

C++20のmodulesとしてWebCFaceをimportすることもできます。

import webcface;

#include <webcface/webcface.h> と同様 webcface:: 以下のすべての機能が使えるようになります。

include/webcface/modules/webcface.ccm として module interface unit のソースファイルがインストールされるので、それをプロジェクトのソースに追加してコンパイルすることで利用できます。 ビルド済みのBMIはインストールしないので、コンパイラのバージョンの互換性を気にする必要はありません。

Warning

通常CMakeを使えばどのコンパイラでも .ccm をモジュールのファイルとして受け付けますが、本来の module interface unit のファイル拡張子はコンパイラごとに異なります。(参考: https://stackoverflow.com/questions/75733706/what-is-the-file-extension-naming-convention-for-c20-modules ) WebCFaceでは以下の3つのファイルをインストールするので、使用できる拡張子に制限がある場合はいずれかを利用してください。内容はどれでも同じです。

• GCC用: include/webcface/modules/webcface.cc
• Clang用: include/webcface/modules/webcface.ccm
• MSVC用: include/webcface/modules/webcface.ixx

• Meson Meson側でのmodulesサポート機能は完全ではないので、以下のようにソースファイルの指定などを手動で行う必要があります。 (詳細は https://github.com/mesonbuild/meson/issues/5024 )

  webcface_dep = dependency('webcface', version: '>=3.0.0')
   
  cxx = meson.get_compiler('cpp')
  if cxx.get_id() == 'gcc' and cxx.version().version_compare('>=14')
    # see https://github.com/mesonbuild/meson/issues/6660
    webcface_miu = webcface_dep.get_variable(pkgconfig: 'includedir', cmake: 'PACKAGE_INCLUDE_DIRS') / 'webcface/modules/webcface.cc'
    # https://github.com/ninja-build/ninja/issues/1962
    modules_args = ['-fmodules-ts', '-fdeps-format=p1689r5']
  elif cxx.get_argument_syntax() == 'msvc'
    webcface_miu = webcface_dep.get_variable(pkgconfig: 'includedir', cmake: 'PACKAGE_INCLUDE_DIRS') / 'webcface/modules/webcface.ixx'
    modules_args = []
  else
    error('現在のMesonはclangでのmodulesには非対応')
  fi
   
  # webcface_depに加えて、webcface_miuと追加のフラグ(gccのみ)をプロジェクトに追加
  executable('main', 'main.cc', webcface_miu,
    dependencies: [webcface_dep],
    cpp_args: modules_args,
  )

• CMake CMakeのバージョンが3.28以上の場合、webcface::webcface の代わりに webcface::webcface_modules をリンクすることで、 module interface unit が自動的にターゲットのソースに追加されます。

  find_package(webcface 3.0 CONFIG REQUIRED)
   
  target_link_libraries(your-target PRIVATE webcface::webcface_modules)

  Note

  webcface::webcface_modules ターゲットには cpp_std_20 の指定が含まれています。

  Warning

  プロジェクトのcmake_minimum_requiredが3.28未満(CMP0155がOLD)の場合、modules関連のコンパイルオプションがCMakeによって正しく適用されない可能性があります。

Python

Pythonで利用したい場合は pip install webcface でライブラリをインストールしてください。 Python3.6以上で動作します。

importは

import webcface

で webcface.Client のように使うか、

from webcface import Client

のように使います。

使い方はC++のライブラリとだいたい同じです。 次ページ以降のドキュメントとともに webcface-python APIリファレンス も参照してください

JavaScript/TypeScript

npm install webcface でライブラリをインストールできます。 Node.jsでもブラウザー(webpackなど)でも動きます。

Node.jsの場合、ESMで

import { Client } from "webcface";

のようにして使うことができます。 CommonJSでrequires("webcface")のように使うこともできると思います。

1.7 ブラウザー上で使う場合はCDNも利用できます。

<script src="https://cdn.jsdelivr.net/npm/webcface@1.11.0/dist/webcface.bundle.js"></script>

で読み込むとグローバルに webcface.Client などが使用できるようになります。

使い方はC++のライブラリとだいたい同じです。 次ページ以降のドキュメントとともに webcface-js APIリファレンス も参照してください。

Previous	Next
2-2. WebUI	3-2. Building from Source