maxmustermann/pulumi
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update the CIDLC README with build, running, etc. instructions

Browse source
This commit is contained in:
joeduffy 2017-04-30 08:36:57 -07:00
parent 35a86d9089
commit 69df382da9
2 changed files with 37 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
cmd/cidlc/README.md
View file

@ -1,29 +1,52 @@
# cocogo
# cidlc
CocoGo compiles Go programs into Coconut metadata and packages.
CIDLC compiles an Go-based IDL into Coconut metadata and packages.
## IDL
CIDLC accepts a subset of Go. Please refer to [the IDL design document](/docs/idl.md) for details.
## Providers
The primary use case for CocoGo is to author resource packages and providers. A resource package is a low level
The primary use case for CIDLC is to author resource packages and providers. A resource package is a low level
Coconut package with metadata associated with a set of resource type definitions. Its associated provider is a dynamic
plugin that implements the behavior associated with those resources, their CRUD functions, and operational semantics.
The CocoGo toolset cuts down on boilerplate and makes it easy to author new resource packages and providers.
The CIDLC toolset cuts down on boilerplate and makes it easy to author new resource packages and providers.
## Building
To build the CIDLC tool, run
$ go install github.com/pulumi/coconut/cmd/cidlc
from an enlistment with a proper `GOPATH` set.
## Running
To generate code, run:
$ cocogo [packages]
$ cidlc pkg-name idl-path [flags]
where the packages are a set of package names to compile. All Go code for those packages must be legal CocoGo, a vast
subset of the overall Go programming language. At the moment, only what is necessary for IDL is supported.
where the `pkg-name` is the name of the target Coconut package, `idl-path` is a path to a directory containing IDL, and
`flags` are an optional set of flags. All `*.go` files in the target directory are parsed and processed as IDL. To
recursively fetch sub-packages, pass the `--recursive` (or `-r`) flag.
The output includes the following:
* A `Cocopack.json` package, containing all of the resource definitions.
* An output containing Go code for the resource provider:
* A Coconut package in CocoJS, containing resource definitions.
* An RPC package in Go to aid in the creation of a resource provider, containing:
- A base resource provider that handles marshaling goo at the edges.
- A marshalable type for each resource type (used for dynamic plugin serialization).
Afterwards, the Coconut package is given out to consumers that can use CocoPy, CocoRu, CocoJS, etc. And the compiled
provider implements the behavior associated with the resource.
The two flags, `--out-pack` and `--out-rpc` control if and where the output will be generated, respectively. It is
possible to specify just one or the other, or you can generate both simultaneously.
By default, the IDL Go package is inferred from a combination of `idl-path` and `GOPATH`. This is used to generate
inter- and intra-package references. If you are generating RPC code, that too is inferred, based on `--out-rpc` and
`GOPATH`. In the event you are running outside of a Go workspace (where `GOPATH` is not set), or need to customize
these, the packages can be set by hand using the flags `--pkg-base-idl` and `--pkg-base-rpc`, respectively.
After generating the code and implementing behavior associated with the resource in the provider, the Coconut package
may then be distributed to consumers using CocoPy, CocoRu, CocoJS, and other CocoLangs.

6
cmd/cidlc/cidlc.go
View file

@ -22,13 +22,13 @@ func NewCIDLCCmd() *cobra.Command {
var recursive bool
var verbose int
cmd := &cobra.Command{
Use: "cidlc [pkg-name] [idl-path]",
Use: "cidlc pkg-name idl-path",
Short: "CIDLC generates Coconut metadata and RPC stubs from IDL written in Go",
Long: "CIDLC generates Coconut metadata and RPC stubs from IDL written in Go.\n" +
"\n" +
"The tool accepts a subset of Go types and produces packages that can be consumed by\n" +
"ordinary Coconut programs and libraries in any language. The [pkg-name] argument\n" +
"controls the output package name and [idl-path] is the path to the IDL sourcecode.\n" +
"ordinary Coconut programs and libraries in any language. The pkg-name argument\n" +
"controls the output package name and idl-path is the path to the IDL source code.\n" +
"\n" +
"The --out-pack and --out-rpc flags indicate where generated code is to be saved,\n" +
"and pkg-base-idl and --pkg-base-rpc may be used to override the default inferred Go\n" +