Merge pull request #5524 from dgquintas/templates_readme

updated templates/README.md

templates/README.md

@@ -6,78 +6,91 @@ was going to single handedly cover all of our usage cases.
 
 So instead we decided to work the following way:
 
-* A build.json file at the root is the source of truth for listing all of the
-target and files needed to build grpc and its tests, as well as basic system
-dependencies description.
+* A `build.yaml` file at the root is the source of truth for listing all the
+targets and files needed to build grpc and its tests, as well as a basic system
+for dependency description.
 
 * Each project file (Makefile, Visual Studio project files, Bazel's BUILD) is
-a plain-text template that uses the build.json file to generate the final
-output file.
+a [YAML](http://yaml.org) file used by the `build.yaml` file to generate the
+final output file.
 
 This way we can maintain as many project system as we see fit, without having
 to manually maintain them when we add or remove new code to the repository.
 Only the structure of the project file is relevant to the template. The actual
 list of source code and targets isn't.
 
-We currently have template files for GNU Make, Visual Studio 2010 to 2015,
-and Bazel. In the future, we would like to expand to generating gyp or cmake
-project files (or potentially both), XCode project files, and an Android.mk
-file to be able to compile gRPC using Android's NDK.
+We currently have template files for GNU Make, Visual Studio 2013,
+[Bazel](http://bazel.io) and [gyp](https://gyp.gsrc.io/). In the future, we
+would like to expand to also generate [cmake](https://cmake.org)
+project files, XCode project files, and an Android.mk file allowing to compile
+gRPC using Android's NDK.
 
 We'll gladly accept contribution that'd create additional project files
 using that system.
 
-# Structure of build.json
+# Structure of `build.yaml`
 
-The build.json file has the following structure:
+The `build.yaml` file has the following structure:
 
 ```
-{
-  "settings": { ... },   # global settings, such as version number
-  "filegroups": [ ... ], # groups of file that is automatically expanded
-  "libs": [ ... ],       # list of libraries to build
-  "targets": [ ... ],    # list of targets to build
-}
+settings:  # global settings, such as version number
+  ...
+filegroups:  # groups of files that are automatically expanded
+  ...
+libs:  # list of libraries to build
+  ...
+target:   # list of targets to build
+  ...
 ```
 
 The `filegroups` are helpful to re-use a subset of files in multiple targets.
 One `filegroups` entry has the following structure:
 
 ```
-{
-  "name": "arbitrary string", # the name of the filegroup
-  "public_headers": [ ... ],  # list of public headers defined in that filegroup
-  "headers": [ ... ],         # list of headers defined in that filegroup
-  "src": [ ... ],             # list of source files defined in that filegroup
-}
+- name: "arbitrary string", # the name of the filegroup
+  public_headers: # list of public headers defined in that filegroup
+  - ...
+  headers: # list of headers defined in that filegroup
+  - ...
+  src: # list of source files defined in that filegroup
+  - ...
 ```
 
-The `libs` array contains the list of all the libraries we describe. Some may be
+The `libs` collection contains the list of all the libraries we describe. Some may be
 helper libraries for the tests. Some may be installable libraries. Some may be
 helper libraries for installable binaries.
 
 The `targets` array contains the list of all the binary targets we describe. Some may
 be installable binaries.
 
-One `libs` or `targets` entry has the following structure:
+One `libs` or `targets` entry has the following structure (see below for
+details):
 
 ```
-{
-  "name": "arbitrary string", # the name of the library
-  "build": "build type",      # in which situation we want that library to be
-                              # built and potentially installed
-  "language": "...",          # the language tag; "c" or "c++"
-  "public_headers": [ ... ],  # list of public headers to install
-  "headers": [ ... ],         # list of headers used by that target
-  "src": [ ... ],             # list of files to compile
-  "secure": "...",            # "yes", "no" or "check"
-  "baselib": boolean,         # this is a low level library that has system
-                              # dependencies
-  "vs_project_guid: "...",    # Visual Studio's unique guid for that project
-  "filegroups": [ ... ],      # list of filegroups to merge to that project
-                              # note that this will be expanded automatically
-  "deps": [ ... ],            # list of libraries this target depends on
-}
+name: "arbitrary string", # the name of the library
+build: "build type",      # in which situation we want that library to be
+                          # built and potentially installed (see below).
+language: "...",          # the language tag; "c" or "c++"
+public_headers:           # list of public headers to install
+headers:                  # list of headers used by that target
+src:                      # list of files to compile
+secure: boolean,          # see below
+baselib: boolean,         # this is a low level library that has system
+                          # dependencies
+vs_project_guid: '{...}', # Visual Studio's unique guid for that project
+filegroups:               # list of filegroups to merge to that project
+                          # note that this will be expanded automatically
+deps:                     # list of libraries this target depends on
+deps_linkage: "..."       # "static"  or "dynamic". Used by the Makefile only to
+                          # determine the way dependencies are linkned. Defaults
+                          # to "dynamic".
+dll: "..."                # see below.
+dll_def: "..."            # Visual Studio's dll definition file.
+vs_props:                 # List of property sheets to attach to that project.
+vs_config_type: "..."     # DynamicLibrary/StaticLibrary. Used only when
+                          # creating a library. Specifies if we're building a
+                          # static library or a dll. Use in conjunction with `dll_def`.
+vs_packages:              # List of nuget packages this project depends on.
 ```
 
 ## The `"build"` tag
@@ -86,8 +99,9 @@ Currently, the "`build`" tag have these meanings:
 
 * `"all"`: library to build on `"make all"`, and install on the system.
 * `"protoc"`: a protoc plugin to build on `"make all"` and install on the system.
-* `"priviate"`: a library to only build for tests.
+* `"private"`: a library to only build for tests.
 * `"test"`: a test binary to run on `"make test"`.
+* `"tool"`: a binary to be built upon `"make tools"`.
 
 All of the targets should always be present in the generated project file, if
 possible and applicable. But the build tag is what should group the targets
@@ -111,6 +125,18 @@ should merge OpenSSL, protobuf or zlib inside that library. That effect depends
 on the `"language"` tag. OpenSSL and zlib are for `"c"` libraries, while
 protobuf is for `"c++"` ones.
 
+## The `"dll"` tag
+
+Used only by Visual Studio's project files. "true" means the project will be
+built with both static and dynamic runtimes. "false" means it'll only be built
+with static runtime. "only" means it'll only be built with the dll runtime.
+
+## The `"dll_def"` tag
+
+Specifies the visual studio's dll definition file. When creating a DLL, you
+sometimes (not always) need a def file (see grpc.def).
+
+
 # The template system
 
 We're currently using the [mako templates](http://www.makotemplates.org/)