Update the CIDLC README with build, running, etc. instructions
This commit is contained in:
parent
35a86d9089
commit
69df382da9
2 changed files with 37 additions and 14 deletions
|
@ -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.
|
||||
|
||||
|
|
|
@ -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" +
|
||||
|
|
Loading…
Reference in a new issue