Skip to content

Commit 0b118ce

Browse files
wraverywravery
committed
Update the docs #52 
1 parent 692dcca commit 0b118ce

File tree

1 file changed

+102
-68
lines changed

1 file changed

+102
-68
lines changed

‎README.md

Lines changed: 102 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -25,51 +25,104 @@ app and your native/hybrid app.
2525

2626
## Related projects
2727

28-
I created a couple of sample projects to demonstrate integrating the [schema.today.graphql](./samples/today/schema.today.graphql)
29-
service into an Electron app. They're available under my personal account, feel free to use either or both of these as a
30-
starting point to integrate your own generated service with Node or Electron:
31-
* [electron-cppgraphql](https://github.com/wravery/electron-cppgraphql): Node Native Module which compiles
28+
I created a couple of sample projects that worked up to version 2.x to demonstrate integrating the
29+
[schema.today.graphql](./samples/today/schema.today.graphql) service into an Electron app. I haven't migrated them
30+
to 3.x and C++17 yet, but they're available under my personal account. Feel free to use either or both of these as a
31+
starting point to integrate your own generated service with Node or Electron. PRs with links to your own samples or
32+
migrating either of those projects to 3.x are welcome.
33+
34+
- [electron-cppgraphql](https://github.com/wravery/electron-cppgraphql): Node Native Module which compiles
3235
against the version of the Node headers included in Electron.
33-
* [cppgraphiql](https://github.com/wravery/cppgraphiql): Electron app which consumes `electron-cppgraphql` and
36+
- [cppgraphiql](https://github.com/wravery/cppgraphiql): Electron app which consumes `electron-cppgraphql` and
3437
exposes an instance of [GraphiQL](https://github.com/graphql/graphiql) on top of it.
3538

3639
## Installation process
3740

38-
First, clone this repo, then make sure you have the dependencies. Acquiring the dependencies is a
39-
bit different depending on your platform.
41+
I've tested this on Windows with Visual Studio 2019 and Linux using an Ubuntu 18.04 LTS instance running in WSL with
42+
both gcc 7.3.0 and clang 6.0.0. The key compiler requirement is support for C++17, recent updates to Visual Studio 2017
43+
will probably work too.
4044

41-
I've tested this on Windows with Visual Studio 2017 and Linux using an Ubuntu instance running in
42-
WSL.
45+
The easiest way to get all of these and to build `cppgraphqlgen` in one step is to use
46+
[Microsoft/vcpkg](https://github.com/Microsoft/vcpkg). To install with vcpkg, make sure you've pulled the latest version
47+
and then run `vcpkg install cppgraphqlgen` (or `cppgraphqlgen:x64-windows`, `cppgraphqlgen:x86-windows-static`, etc.
48+
depending on your platform). To install just the dependencies and work in a clone of this repo, you'll need some subset
49+
of `vcpkg install pegtl boost-program-options boost-filesystem rapidjson gtest`. It works for Windows, Linux, and Mac,
50+
but if you want to try building for another platform (e.g. Android or iOS), you'll need to do more of this manually.
4351

44-
I added a vcpkg port for this project, if you have vcpkg you can also install everything with `vcpkg install cppgraphqlgen`.
52+
Manual installation will work best if you clone the GitHub repos for each of the dependencies and follow the installation
53+
instructions for each project. You might also be able to find pre-built packages depending on your platform, but the
54+
versions need to match.
4555

4656
## Software dependencies
4757

48-
As of version 3.0, this project depends on C++17. I also picked a few other projects as dependencies:
58+
The build system for this project uses [CMake](http://www.cmake.org/). You will need to have CMake (at least version
59+
3.8.0) installed, and the library dependencies need to be where CMake can find them. Otherwise you need to disable the
60+
options which depend on them.
4961

50-
- GraphQL parsing: [Parsing Expression Grammar Template Library (PEGTL)](https://github.com/taocpp/PEGTL), which is part of [The Art of C++](https://taocpp.github.io/) library collection. While the PEGTL 3.0 release is still pending I've added this as a sub-module, so you should not install this separately.
51-
- Command line handling: [Boost.Program_options](https://www.boost.org/doc/libs/1_69_0/doc/html/program_options.html).
52-
- JSON support: [RapidJSON](https://github.com/Tencent/rapidjson).
53-
- Unit testing: [Google Test](https://github.com/google/googletest) for the unit testing framework.
62+
I also picked a few other projects as dependencies, most of which are optional when consuming this project. If you
63+
redistribute any binaries built from these libraries, you should still follow the terms of their individual licenses. As
64+
of this writing, this library and all of its redistributable dependencies are available under the MIT license, which
65+
means you need to include an acknowledgement along with the license text.
66+
67+
### graphqlpeg
68+
69+
- GraphQL parsing: [Parsing Expression Grammar Template Library (PEGTL)](https://github.com/taocpp/PEGTL) release 3.0.0,
70+
which is part of [The Art of C++](https://taocpp.github.io/) library collection. I've added this as a sub-module, so you
71+
do not need to install this separately. If you already have 3.0.0 installed where CMake can find it, it will use that
72+
instead of the sub-module and avoid installing another copy of PEGTL. _Note: PEGTL 3.0.0 is currently at pre-release._
5473

55-
The build system for this project uses [CMake](http://www.cmake.org/). You'll need to have all of the
56-
dependencies installed on your system along with CMake to build this project.
74+
### graphqlservice
5775

58-
### Using vcpkg
76+
The core library depends on `graphqlpeg` and it references the PEGTL headers itself at build time. Both of those mean it
77+
depends on PEGTL as well.
5978

60-
Vcpkg can install the dependencies from source on either platform, and that's what I'm using on Windows and Linux.
61-
PEGTL is currently included as a sub-module of this repo, so you can just use `vcpkg install boost-program-options rapidjson gtest`
62-
to get all of the others.
79+
### graphqljson (`GRAPHQL_USE_RAPIDJSON=ON`)
6380

64-
### Windows with NuGet
81+
- JSON support: [RapidJSON](https://github.com/Tencent/rapidjson) release 1.1.0. If you don't need JSON support, you can
82+
also avoid installing this dependency. You will need to set `GRAPHQL_USE_RAPIDJSON=OFF` in your CMake configuration to
83+
do that.
6584

66-
All of these packages dependencies should also be available in NuGet packages if you don't want to
67-
use [vcpkg](https://github.com/Microsoft/vcpkg) but still want to use a package manager.
85+
### schemagen
6886

69-
### Linux or Windows from GitHub
87+
I'm using [Boost](https://www.boost.org/doc/libs/1_69_0/more/getting_started/index.html) for `schemagen`:
7088

71-
Clone each of the repos from GitHub and follow the installation instructions in the README.md
72-
files.
89+
- C++17 std::filesystem support on Unix:
90+
[Boost.Filesystem](https://www.boost.org/doc/libs/1_69_0/libs/filesystem/doc/index.htm). Most of the default C++
91+
compilers on Linux still have `std::filesystem` from C++17 in an experimental directory and require an extra
92+
library. The standard just adopted the Boost library, so on Unix systems I have an `#ifdef` which redirects back to
93+
it for the time being.
94+
- Command line handling: [Boost.Program_options](https://www.boost.org/doc/libs/1_69_0/doc/html/program_options.html).
95+
Run `schemagen -?` to get a list of options. Many of the files in the [samples](samples/) directory were generated
96+
with `schemagen`, you can look at [samples/CMakeLists.txt](samples/CMakeLists.txt) for a few examples of how to call it:
97+
```
98+
Usage: schemagen [options] <schema file> <output filename prefix> <output namespace>
99+
Command line options:
100+
-? [ --help ] Print the command line options
101+
-v [ --verbose ] Verbose output including generated header names as
102+
well as sources
103+
-s [ --schema ] arg Schema definition file path
104+
-p [ --prefix ] arg Prefix to use for the generated C++ filenames
105+
-n [ --namespace ] arg C++ sub-namespace for the generated types
106+
--source-dir arg Target path for the <prefix>Schema.cpp source file
107+
--header-dir arg Target path for the <prefix>Schema.h header file
108+
--no-stubs Generate abstract classes without stub implementations
109+
--separate-files Generate separate files for each of the types
110+
```
111+
112+
I've only tested this with Boost 1.69.0, but I expect it will work fine with most other versions. The Boost dependencies
113+
are only used by the `schemagen` utility at or before your build, so you probably don't need to redistribute it or the
114+
Boost libraries with your project.
115+
116+
If you are building shared libraries on Windows (DLLs) using vcpkg or `BUILD_SHARED_LIBS=ON` in CMake, be aware that this
117+
adds a runtime dependency on a Boost DLL. The `schemagen` tool won't run without it. However, in addition to automating
118+
the install of Boost, vcpkg also takes care of installing the dependencies next to `schemagen.exe` when building the
119+
Windows and UWP shared library targets (the platform triplets which don't end in `-static`).
120+
121+
### tests (`GRAPHQL_BUILD_TESTS=ON`)
122+
123+
- Unit testing: [Google Test](https://github.com/google/googletest) for the unit testing framework. If you don't want to
124+
build or run the unit tests, you can avoid this dependency as well by setting `GRAPHQL_BUILD_TESTS=OFF` in your CMake
125+
configuration.
73126

74127
## API references
75128

@@ -81,63 +134,44 @@ in [schema.today.graphql](samples/today/schema.today.graphql) for testing purpos
81134
All of the generated files are in the [samples](samples/) directory. There are two different versions of
82135
the generated code, one which creates a single pair of files (`samples/unified/`), and one which uses the
83136
`--separate-files` flag with `schemagen` to generate individual header and source files (`samples/separate/`)
84-
for each of the object types which need to be implemeneted. The only difference between [UnifiedToday.h](samples/today/UnifiedToday.h)
137+
for each of the object types which need to be implemeneted. The only difference between
138+
[UnifiedToday.h](samples/today/UnifiedToday.h)
85139
and [SeparateToday.h](samples/today/SeparateToday.h) should be that the `SeparateToday` use a generated
86140
[TodayObjects.h](samples/separate/TodayObjects.h) convenience header which includes all of the inidividual
87-
object header along with the rest of the schema in [TodaySchema.h](samples/separate/TodaySchema.h).
88-
89-
If you modify the code generator in SchemaGenerator.* and rebuild, `make install` will update them. Please
90-
remember to include updating the samples in any pull requests which change them.
141+
object header along with the rest of the schema in [TodaySchema.h](samples/separate/TodaySchema.h). If you modify the
142+
code generator in SchemaGenerator.* and rebuild, building the install target will update them. Please remember to
143+
include updating the samples in any pull requests which change them.
91144

92145
# Build and Test
93146

94-
## Windows
95-
96-
There are a couple of options for building on Windows. You can either run CMake from the command
97-
line, or you can use the CMake integration in Visual Studio. They behave a little differently, but
98-
I prefer building and running tests in Visual Studio, then optionally performing a Release build
99-
and install from the command line.
100-
101-
### Visual Studio
147+
### Visual Studio on Windows
102148

103149
Use the Open Folder command to open the root of the repo. If you've installed the dependencies with
104150
vcpkg and run its Visual Studio integration command, Visual Studio should know how to build each of
105-
the targets in this project automatically. I've only been able to get x86-debug to work so far in
106-
Visual Studio though, it doesn't switch properly between the Debug and Release dependencies
107-
installed by vcpkg on my machine.
108-
109-
### Command Line
110-
111-
To build from the command line, run:
112-
113-
`cmake -DCMAKE_TOOLCHAIN_FILE=<...path to vcpkg root...>/scripts/buildsystems/vcpkg.cmake .` once
114-
to populate the Visual Studio solution files, then:
115-
116-
`msbuild cppgraphql.sln` to perform the build.
117-
118-
You can also build optional `.vcxproj` project files with msbuild to perform the associated task,
119-
e.g. installing or running tests.
120-
121-
If you want to make a Release build, add the `/p:Configuration=Release` argument to the `msbuild`
122-
command line.
123-
124-
## Linux
151+
the targets in this project automatically.
125152

126-
To build everything on Linux run:
153+
Once you've built the project Visual Studio's Test Explorer window should list the unit tests, and you
154+
can run all of them from there.
127155

128-
`cmake .`
156+
### Command Line on any platform
129157

130-
`make`
158+
Your experience will vary depending on your build toolchain. The same instructions should work for any platform that
159+
CMake supports. These basic steps will build and run the tests. You can add options to build in another target directory,
160+
change the config from `Debug` (default) to `Release`, use another build tool like `Ninja`, etc. If you are using vcpkg
161+
to install the dependencies, remember to specify the `-DCMAKE_TOOLCHAIN_FILE=...` option when you run the initial build
162+
configuration.
131163

132-
You can then optionally install the public outputs by running:
164+
- Configure the build system: `"cmake ."`
165+
- Tell CMake to invoke the build system: `"cmake --build ."` _You can repeat this step to rebuild your changes._
166+
- CTest comes with CMake and runs the tests: `"ctest ."` _Run this frequently, and make sure it passes before commits._
133167

134-
`sudo make install`.
168+
You can then optionally install the public outputs by running.
135169

136-
## Testing
170+
- `cmake --build . --config Release --target install` _You probably need to use `sudo` on Unix to do this._
137171

138-
Run the unit tests with `tests` from the build output directory.
172+
## Interactive tests
139173

140-
If you want to try an interactive version, you can run `test_today` and paste in queries against
174+
If you want to try an interactive version, you can run `samples/sample` and paste in queries against
141175
the same mock service or load a query from a file on the command line.
142176

143177
## Reporting Security Issues

0 commit comments

Comments
 (0)