Skip to content

C
capnproto
Commit 871d90c6 authored by Kenton Varda's avatar Kenton Varda
Browse files
Options

More docs.

parent 7eb36033
Hide whitespace changes
Inline Side-by-side
Showing with 70 additions and 8 deletions
doc/_layouts/page.html
View file @ 871d90c6
......@@ -8,7 +8,7 @@
<link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css">
<title>Capnproto</title>
<title>Cap'n Proto</title>
</head>
<body>
......@@ -18,7 +18,7 @@
<header class="inner">
<a id="forkme_banner" href="https://github.com/kentonv/capnproto">View on GitHub</a>
<h1 id="project_title">Capnproto</h1>
<h1 id="project_title">Cap'n Proto</h1>
<h2 id="project_tagline">Cap'n Proto serialization/RPC system</h2>
<section id="downloads">
......@@ -75,7 +75,7 @@
<!-- FOOTER -->
<div id="footer_wrap" class="outer">
<footer class="inner">
<p class="copyright">Capnproto maintained by <a href="https://github.com/kentonv">kentonv</a></p>
<p class="copyright">Cap'n Proto maintained by <a href="https://github.com/kentonv">kentonv</a></p>
<p>Published with <a href="http://pages.github.com">GitHub Pages</a></p>
</footer>
</div>
......
doc/_plugins/capnp_lexer.py
View file @ 871d90c6
......@@ -12,14 +12,36 @@ class CapnpLexer(RegexLexer):
'root': [
(r'#.*?$', Comment.Single),
(r'@[0-9]*', Name.Decorator),
(r'=[^;]*', Literal),
(r':[^;=]*', Name.Class),
(r'=', Literal, 'expression'),
(r':', Name.Class, 'type'),
(r'@[0-9]*', Token.Annotation),
(r'(struct|enum|interface|union|import|using|const|option|in|of|on|as|with|from)\b',
Token.Keyword),
(r'[a-zA-Z0-9_.]+', Token.Name),
(r'[^#@=:a-zA-Z0-9_]+', Text),
]
],
'type': [
(r'[^][=;,()]+', Name.Class),
(r'[[(]', Name.Class, 'parentype'),
(r'', Name.Class, '#pop')
],
'parentype': [
(r'[^][;()]+', Name.Class),
(r'[[(]', Name.Class, '#push'),
(r'[])]', Name.Class, '#pop'),
(r'', Name.Class, '#pop')
],
'expression': [
(r'[^][;,()]+', Literal),
(r'[[(]', Literal, 'parenexp'),
(r'', Literal, '#pop')
],
'parenexp': [
(r'[^][;()]+', Literal),
(r'[[(]', Literal, '#push'),
(r'[])]', Literal, '#pop'),
(r'', Literal, '#pop')
],
}
if __name__ == "__main__":
......
doc/install.md
View file @ 871d90c6
......@@ -24,9 +24,27 @@ Therefore, you should only be installing Cap'n Proto at this time if you just wa
with it or help develop it. If so, great! Please report your findings to the
[discussion group](https://groups.google.com/group/capnproto).
## Installing the Cap'n Proto Compiler
`capnpc`, which takes `.capnp` files and generates source code for them (e.g. in C++), is itself
written in Haskell.
First, install [Cabal](http://www.haskell.org/cabal/), e.g. on Ubuntu:
sudo apt-get install cabal-install
Now you can check out, build, and install `capnpc` like so:
git clone https://github.com/kentonv/capnproto.git
cd capnproto/compiler
cabal install capnproto-compiler.cabal
Be sure that the Cabal bin directory (typically `$HOME/.cabal/bin`) is in your `PATH` before you
attempt to build the C++ runtime.
## Installing the C++ Runtime
### Recent Compiler Needed
### GCC 4.7 Needed
If you are using GCC, you MUST use at least version 4.7 as Cap'n Proto uses recently-implemented
C++11 features. If you are using some other compiler... good luck.
......
doc/language.md
View file @ 871d90c6
......@@ -195,7 +195,9 @@ struct FileInfo {
}
interface File {
read @0 (startAt :UInt64, amount :UInt64) :Data;
read @0 (startAt :UInt64 = 0, amount :UInt64 = 0xffffffffffffffff) :Data;
# Default params = read entire file.
write @1 (startAt :UInt64, data :Data) :Void;
truncate @2 (size :UInt64) :Void;
}
......@@ -289,6 +291,26 @@ struct Foo {
}
{% endhighlight %}
## Evolving Your Protocol
A protocol can be changed in the following ways without breaking backwards-compatibility:
* New types, constants, and aliases can be added anywhere, since they obviously don't affect the
encoding of any existing type.
* New fields, values, and methods may be added to structs, enums, and interfaces, respectively,
with the numbering rules described earlier.
* New parameters may be added to a method. The new parameters must be added to the end of the
parameter list and must have default values.
* Any symbolic name can be changed, as long as the ordinal numbers stay the same.
* A field of type `List(T)`, where `T` is NOT a struct type, may be changed to type `List(U)`,
where `U` is a struct type whose field number 0 is of type `T`. This rule is useful when you
realize too late that you need to attach some extra data to each element of your list. Without
this rule, you would be stuck defining parallel lists, which are ugly.
Any other change should be assumed NOT to be safe. Also, these rules only apply to the Cap'n Proto
native encoding. It is sometimes useful to transcode Cap'n Proto types to other formats, like
JSON, which may have different rules (e.g., field names cannot change in JSON).
## Running the Compiler
Simply run:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment