{"id":13499469,"url":"https://github.com/Microsoft/cppgraphqlgen","last_synced_at":"2025-03-29T05:31:27.013Z","repository":{"id":33494973,"uuid":"142608516","full_name":"microsoft/cppgraphqlgen","owner":"microsoft","description":"C++ GraphQL schema service generator","archived":false,"fork":false,"pushed_at":"2024-07-18T05:32:35.000Z","size":2854,"stargazers_count":318,"open_issues_count":6,"forks_count":45,"subscribers_count":20,"default_branch":"main","last_synced_at":"2024-07-18T07:22:42.766Z","etag":null,"topics":["graphql","graphql-tools"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-27T17:59:34.000Z","updated_at":"2024-07-18T05:27:44.000Z","dependencies_parsed_at":"2023-11-17T21:30:33.703Z","dependency_job_id":"0bd9694c-b27a-4a90-8240-01b9d0db1efd","html_url":"https://github.com/microsoft/cppgraphqlgen","commit_stats":null,"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fcppgraphqlgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fcppgraphqlgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fcppgraphqlgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fcppgraphqlgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/cppgraphqlgen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":213424220,"owners_count":15585267,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graphql","graphql-tools"],"created_at":"2024-07-31T22:00:33.427Z","updated_at":"2024-10-31T18:30:30.450Z","avatar_url":"https://github.com/microsoft.png","language":"C++","readme":"# Introduction\n\n![Windows](https://github.com/microsoft/cppgraphqlgen/workflows/Windows/badge.svg)\n![macOS](https://github.com/microsoft/cppgraphqlgen/workflows/macOS/badge.svg)\n![Linux](https://github.com/microsoft/cppgraphqlgen/workflows/Linux/badge.svg)\n\n[GraphQL](https://graphql.org/) and [React](https://reactjs.org/) go together like peanut butter\nand jelly, especially if you use a GraphQL client/compiler like [Relay](http://facebook.github.io/relay/en/)\nor [Apollo](https://github.com/apollographql/apollo-client).\n\nBut GraphQL services are only implemented on the server. When using React Native or React JS in a\nhybrid application, you typically have a native application which hosts islands or entire pages of\nUI rendered with React components, and you might like to display content that you've cached offline\nor that you otherwise generate on the client without needing to declare a separate data interface\nor require a server round trip to load it.\n\nThis project includes a `graphqlservice` library with the core functionality of a GraphQL service\nand a `schemagen` utility to generate types for your custom GraphQL service schema definition. Once\nyou implement the pure virtual methods on the object interfaces and add hooks to the Relay\n[Network Layer](https://facebook.github.io/relay/docs/en/network-layer.html)/Apollo\n[Terminating Link](https://www.apollographql.com/docs/link/overview.html#terminating) to call your\nservice, you can use the same GraphQL client code to access your native data source or a GraphQL\nservice online. You might even be able to share some more of that code between a progressive web\napp and your native/hybrid app.\n\nIf what you're after is a way to consume a GraphQL service from C++, this project also includes\na `graphqlclient` library and a `clientgen` utility to generate types matching a GraphQL request\ndocument, its variables, and all of the serialization code you need to talk to a `graphqlservice`\nimplementation. If you want to consume another service, you will need access to the schema definition\n(rather than the Introspection query results), and you will need be able to send requests along with\nany variables to the service and parse its responses into a `graphql::response::Value` (e.g. with the\n`graphqljson` library) in your code.\n\n## Related projects\n\nThe most complete examples I've built are related to [GqlMAPI](https://github.com/microsoft/gqlmapi):\n- [eMAPI](https://github.com/microsoft/eMAPI): Windows-only Electron app which lets you access\nthe [MAPI](https://en.wikipedia.org/wiki/MAPI) interface used by\n[Microsoft Outlook](https://en.wikipedia.org/wiki/Microsoft_Outlook). Its goal is to be a spiritual\nsuccessor to a debugging and diagnostic tool called\n[MFCMAPI](https://github.com/stephenegriffin/mfcmapi).\n- [electron-gqlmapi](https://github.com/microsoft/electron-gqlmapi): Native module for Electron\nwhich hosts `GqlMAPI` in `eMAPI`. It includes JS libraries for calling the native module across the\nElectron IPC channel.\n- [Tauri-GqlMAPI](https://github.com/wravery/tauri-gqlmapi): Reimplementation of `eMAPI` built\nin [Rust](https://www.rust-lang.org/) and [TypeScript](https://www.typescriptlang.org/) on top of\n[Tauri](https://tauri.studio/en).\n- [gqlmapi-rs](https://github.com/wravery/gqlmapi-rs): `Rust` crate I built to expose safe\nbindings for `GqlMAPI`. It is loosely based on `electron-gqlmapi`, and it is used by\n`Tauri-GqlMAPI`.\n\nI created a couple of sample projects to demonstrate integrating the\n[schema.today.graphql](./samples/schema.today.graphql) service into an Electron app. The\n`schema.today.graphql` schema and service implementation in `TodayMock.*` are focused on testing,\nso the specific bootstrapping used in these projects should not be re-used, but you can use them\nas a scaffold to start your own integration with Electron or Node.js. They're available under\nmy personal account, and I recently updated them to match the latest release of `cppgraphqlgen`:\n- [electron-cppgraphql](https://github.com/wravery/electron-cppgraphql): Node Native Module which compiles\nagainst the version of the Node headers included in Electron. This was the starting point for\n`electron-gqlmapi`, and it is still useful as a sample because it does not depend on a platform-specific\nAPI like `MAPI`, so it works cross-platform.\n- [cppgraphiql](https://github.com/wravery/cppgraphiql): Electron app which consumes `electron-cppgraphql` and\nexposes an instance of [GraphiQL](https://github.com/graphql/graphiql) on top of it.\n\nFeel free to use either or both of these as a starting point to integrate your own generated\nservice with `Node`, `Electron`, or `Tauri`. PRs with links to your own samples are always welcome.\n\n# Getting Started\n\n## Installation process\n\nThe minimum OS and toolchain versions I've tested with this version of `cppgraphqlgen` are:\n- Microsoft Windows: Visual Studio 2019\n- Linux: Ubuntu 20.04 LTS with gcc 10.3.0\n- macOS: 11 (Big Sur) with AppleClang 13.0.0.\n\nThe key compiler requirement is support for C++20 including coroutines and concepts. Some of these compiler\nversions still treat coroutine support as experimental, and the CMake configuration can auto-detect that,\nbut earlier versions of gcc and clang do not seem to have enough support for C++20.\n\nThe easiest way to build and install `cppgraphqlgen` is to use [microsoft/vcpkg](https://github.com/microsoft/vcpkg).\nSee the [Getting Started](https://github.com/microsoft/vcpkg#getting-started) section of the `vcpkg` README\nfor details. Once you have that configured, run `vcpkg install cppgraphqlgen` (or `cppgraphqlgen:x64-windows`,\n`cppgraphqlgen:x86-windows-static`, etc. depending on your platform). That will build and install all of the\ndependencies for `cppgraphqlgen`, and then build `cppgraphqlgen` itself without any other setup. The `cppgraphqlgen`\npackage (and its dependencies) are advertised to the `CMake` `find_package` function through the\n`-DCMAKE_TOOLCHAIN_FILE=\u003c...\u003e/scripts/buildsystems/vcpkg.cmake` parameter/variable. There are more details about\nthis in the `vcpkg` documentation.\n\nIf you want to build `cppgraphqlgen` yourself, you can do that with `CMake` from a clone or archive of this repo.\nSee the [Build and Test](#build-and-test) section below for instructions. You will need to install the dependencies\nfirst where `find_package` can find them. If `vcpkg` works otherwise, you can do that with `vcpkg install pegtl\nboost-program-options rapidjson gtest`. Some of these are optional, if for example you do not build the tests. If\n`vcpkg` does not work, please see the documentation for each of those dependencies, as well as your\nplatform/toolchain documentation for perferred installation mechanisms. You may need to build some or all of them\nseparately from source.\n\n## Software dependencies\n\nThe build system for this project uses [CMake](http://www.cmake.org/). You will need to have CMake (at least version\n3.15.0) installed, and the library dependencies need to be where CMake can find them. Otherwise you need to disable the\noptions which depend on them.\n\nBesides the MIT license for this project, if you redistribute any source code or binaries built from these library\ndependencies, you should still follow the terms of their individual licenses. As of this writing, this library and\nall of its dependencies are available under either the MIT License or the Boost Software License (BSL). Both\nlicenses roughly mean that you may redistribute them freely as long as you include an acknowledgement along with\nthe license text. Please see the license or copyright notice which comes with each project for more details.\n\n### graphqlpeg\n\n- GraphQL parsing: [Parsing Expression Grammar Template Library (PEGTL)](https://github.com/taocpp/PEGTL) release 3.2.6,\nwhich is part of [The Art of C++](https://taocpp.github.io/) library collection. I've added this as a sub-module, so you\ndo not need to install this separately. If you already have 3.2.6 installed where CMake can find it, it will use that\ninstead of the sub-module and avoid installing another copy of PEGTL.\n\n### graphqlservice\n\nThe core library depends on `graphqlpeg` and it references the PEGTL headers itself at build time. Both of those mean it\ndepends on PEGTL as well.\n\n### graphqljson (`GRAPHQL_USE_RAPIDJSON=ON`)\n\n- JSON support: [RapidJSON](https://github.com/Tencent/rapidjson) release 1.1.0. If you don't need JSON support, you can\nalso avoid installing this dependency. You will need to set `GRAPHQL_USE_RAPIDJSON=OFF` in your CMake configuration to\ndo that.\n\n### schemagen\n\nI'm using [Boost](https://www.boost.org/doc/libs/1_82_0/more/getting_started/index.html) for `schemagen`:\n\n- Command line handling: [Boost.Program_options](https://www.boost.org/doc/libs/1_82_0/doc/html/program_options.html).\nRun `schemagen -?` to get a list of options. Many of the files in the [samples](samples/) directory were generated\nwith `schemagen`, you can look at [samples/CMakeLists.txt](samples/CMakeLists.txt) for a few examples of how to call it:\n```\nUsage:  schemagen [options] \u003cschema file\u003e \u003coutput filename prefix\u003e \u003coutput namespace\u003e\nCommand line options:\n  --version              Print the version number\n  -? [ --help ]          Print the command line options\n  -v [ --verbose ]       Verbose output including generated header names as\n                         well as sources\n  -s [ --schema ] arg    Schema definition file path\n  -p [ --prefix ] arg    Prefix to use for the generated C++ filenames\n  -n [ --namespace ] arg C++ sub-namespace for the generated types\n  --source-dir arg       Target path for the \u003cprefix\u003eSchema.cpp source file\n  --header-dir arg       Target path for the \u003cprefix\u003eSchema.h header file\n  --stubs                Unimplemented fields throw runtime exceptions instead\n                         of compiler errors\n  --no-introspection     Do not generate support for Introspection\n```\n\nI've tested this with several versions of Boost going back to 1.65.0. I expect it will work fine with most versions of\nBoost after that. The Boost dependencies are only used by the `schemagen` utility at or before your build, so you\nprobably don't need to redistribute it or the Boost libraries with your project.\n\nIf you are building shared libraries on Windows (DLLs) using vcpkg or `BUILD_SHARED_LIBS=ON` in CMake, be aware that this\nadds a runtime dependency on a Boost DLL. The `schemagen` tool won't run without it. However, in addition to automating\nthe install of Boost, vcpkg also takes care of installing the dependencies next to `schemagen.exe` when building the\nWindows and UWP shared library targets (the platform triplets which don't end in `-static`).\n\n### clientgen\n\nThe `clientgen` utility is based on `schemagen` and shares the same external dependencies. The command line arguments\nare almost the same, except it takes an extra file for the request document and there is no equivalent to `--stubs`:\n```\nUsage:  clientgen [options] \u003cschema file\u003e \u003crequest file\u003e \u003coutput filename prefix\u003e \u003coutput namespace\u003e\nCommand line options:\n  --version              Print the version number\n  -? [ --help ]          Print the command line options\n  -v [ --verbose ]       Verbose output including generated header names as\n                         well as sources\n  -s [ --schema ] arg    Schema definition file path\n  -r [ --request ] arg   Request document file path\n  -o [ --operation ] arg Operation name if the request document contains more\n                         than one\n  -p [ --prefix ] arg    Prefix to use for the generated C++ filenames\n  -n [ --namespace ] arg C++ sub-namespace for the generated types\n  --source-dir arg       Target path for the \u003cprefix\u003eClient.cpp source file\n  --header-dir arg       Target path for the \u003cprefix\u003eClient.h header file\n  --no-introspection     Do not expect support for Introspection\n```\n\nThis utility should output one header and one source file for each request document. A request document may contain more\nthan one operation, in which case it will output definitions for all of them together. You may limit the output to a\nsingle operation from the request document by specifying the `--operation` (or `-o`) argument with the operation name.\n\nThe generated code depends on the `graphqlclient` library for serialization of built-in types. If you link the generated\ncode, you'll also need to link `graphqlclient`, `graphqlpeg` for the pre-parsed, pre-validated request AST, and\n`graphqlresponse` for the `graphql::response::Value` implementation.\n\nSample output for `clientgen` is in the sub-directories of [samples/client](samples/client), and several of them are\nconsumed by unit tests in [test/ClientTests.cpp](test/ClientTests.cpp).\n\n### tests (`GRAPHQL_BUILD_TESTS=ON`)\n\n- Unit testing: [Google Test](https://github.com/google/googletest) for the unit testing framework. If you don't want to\nbuild or run the unit tests, you can avoid this dependency as well by setting `GRAPHQL_BUILD_TESTS=OFF` in your CMake\nconfiguration.\n\n## API references\n\nSee [GraphQLService.h](include/graphqlservice/GraphQLService.h) for the base types implemented in\nthe `graphql::service` namespace.\n\nTake a look at the [samples/learn](samples/learn) directory, starting with\n[StarWarsData.cpp](samples/learn/StarWarsData.cpp) to see a sample implementation of a custom schema defined in\n[schema.learn.graphql](samples/learn/schema/schema.learn.graphql). This is the same schema and sample data used in the\nGraphQL tutorial on https://graphql.org/learn/. This directory builds an interactive command line application which\ncan execute query and mutation operations against the sample data in memory.\n\nThere are several helper functions for `CMake` declared in\n[cmake/cppgraphqlgen-functions.cmake](cmake/cppgraphqlgen-functions.cmake), which is automatically included if you use\n`find_package(cppgraphqlgen)` in your own `CMake` project. See\n[samples/learn/schema/CMakeLists.txt](samples/learn/schema/CMakeLists.txt) and\n[samples/learn/CMakeLists.txt](samples/learn/CMakeLists.txt), or the `CMakeLists.txt` files in some of the\nother samples sub-directories for examples of how to use them to automatically rerun the code generators and update\nthe files in your source directory.\n\n### Migrating from v3.x to main\n\nPlease see the [Migration Guide for v4.x](./doc/migration.md) for more details about upgrading to from the `v3.x` branch\nto the `main` branch. Active development takes place almost entirely in `main`.\n\n### Additional Documentation\n\nThere are some more targeted documents in the [doc](./doc) directory:\n\n* [Awaitable Types](./doc/awaitable.md)\n* [Parsing GraphQL](./doc/parsing.md)\n* [Query Responses](./doc/responses.md)\n* [JSON Representation](./doc/json.md)\n* [Field Resolvers](./doc/resolvers.md)\n* [Field Parameters](./doc/fieldparams.md)\n* [Directives](./doc/directives.md)\n* [Subscriptions](./doc/subscriptions.md)\n\n### Samples\n\nAll of the samples are under [samples](samples/), with nested sub-directories for generated files:\n- [samples/today](samples/today/): There are two different samples generated from\n[schema.today.graphql](samples/today/schema.today.graphql) in this directory. The default\n[schema](samples/today/schema/) target includes Introspection support (which is the default), while the\n[nointrospection](samples/today/nointrospection/) target demonstrates how to disable Introspection support\nwith the `schemagen --no-introspection` parameter. The mock implementation of the service for both schemas is in\n[samples/today/TodayMock.h](samples/today/TodayMock.h) and [samples/today/TodayMock.cpp](samples/today/TodayMock.cpp).\nIt builds an interactive `sample`/`sample_nointrospection` and `benchmark`/`benchmark_nointrospection` target for\neach version, and it uses each of them in several unit tests.\n- [samples/client](samples/client/): Several sample queries built with `clientgen` against the\n[schema.today.graphql](samples/today/schema.today.graphql) schema shared with [samples/today](samples/today/). It\nincludes a `client_benchmark` executable for comparison with benchmark executables using the same hardcoded query\nin [samples/today/]. The benchmark links with the default [schema](samples/today/schema/) target in\n[samples/today](samples/today/) to handle the benchmark query.\n- [samples/learn](samples/learn/): Simpler standalone which builds a `learn_star_wars` executable that follows\nthe tutorial examples on https://graphql.org/learn/.\n- [samples/validation](samples/validation/): This schema is based on the examples and counter-examples from the\n[Validation](https://spec.graphql.org/October2021/#sec-Validation) section of the October 2021 GraphQL spec. There\nis no implementation of this schema, it relies entirely generated stubs (created with `schemagen --stubs`) to build\nsuccessfully without defining more than placeholder objects fo the Query, Mutation, and Subscription operations in\n[samples/validation/ValidationMock.h](samples/validation/ValidationMock.h). It is used to test the validation logic\nwith every example or counter-example in the spec in [test/ValidationTests.cpp](test/ValidationTests.cpp).\n- [samples/proxy](samples/proxy/) (`GRAPHQL_BUILD_HTTP_SAMPLE=ON`): Generates a `client` and `server` pair of\nexecutables which proxy requests from the `client` to the `server` over HTTP (on port 8080 for localhost). The HTTP\nsupport in both samples comes from [Boost.Beast](https://www.boost.org/doc/libs/1_82_0/libs/beast/doc/html/index.html),\nwhich must be included in your `Boost` installation to build this directory. If you are using `vcpkg`, it will install\nthe necessary `Boost` components on demand. _Note: This directory uses the Boost Software License because the samples\nborrow heavily from examples in the `Boost.Beast` documentation._\n\n# Build and Test\n\n### Visual Studio on Windows\n\nUse the Open Folder command to open the root of the repo. If you've installed the dependencies with\nvcpkg and run its Visual Studio integration command, Visual Studio should know how to build each of\nthe targets in this project automatically.\n\nOnce you've built the project Visual Studio's Test Explorer window should list the unit tests, and you\ncan run all of them from there.\n\n### Command Line on any platform\n\nYour experience will vary depending on your build toolchain. The same instructions should work for any platform that\nCMake supports. These basic steps will build and run the tests. You can add options to build in another target directory,\nchange the config from `Debug` (default) to `Release`, use another build tool like `Ninja`, etc. If you are using `vcpkg`\nto install the dependencies, remember to specify the `-DCMAKE_TOOLCHAIN_FILE=...` option when you run the initial build\nconfiguration.\n\n- Create a build directory: `\"mkdir build \u0026\u0026 cd build\"`\n- Configure the build system: `\"cmake ..\"`\n- Tell CMake to invoke the build system: `\"cmake --build .\"` _You can repeat this step to rebuild your changes._\n- CTest comes with CMake and runs the tests: `\"ctest .\"` _Run this frequently, and make sure it passes before commits._\n\nYou can then optionally install the public outputs by configuring it with `Release`:\n- `cmake -DCMAKE_BUILD_TYPE=Release ..`\n- `cmake --build . --target install` _You probably need to use `sudo` on Unix to do this._\n\n## Interactive tests\n\nIf you want to try an interactive version, you can run `samples/today/sample` or `samples/today/sample_nointrospection`\nand paste in queries against the same mock service or load a query from a file on the command line.\n\n## Reporting Security Issues\n\nSecurity issues and bugs should be reported privately, via email, to the Microsoft Security\nResponse Center (MSRC) at [secure@microsoft.com](mailto:secure@microsoft.com). You should\nreceive a response within 24 hours. If for some reason you do not, please follow up via\nemail to ensure we received your original message. Further information, including the\n[MSRC PGP](https://technet.microsoft.com/en-us/security/dn606155) key, can be found in\nthe [Security TechCenter](https://technet.microsoft.com/en-us/security/default).\n\n# Contributing\n\nThis project welcomes contributions and suggestions.  Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit https://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n","funding_links":[],"categories":["Libraries","Implementations"],"sub_categories":["C/C++ Libraries","C/C++"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMicrosoft%2Fcppgraphqlgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMicrosoft%2Fcppgraphqlgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMicrosoft%2Fcppgraphqlgen/lists"}