|
122.3.1
by Julian Edwards
add HACKING.txt and clean up README |
1 |
================================================== |
2 |
Hacking in GWACL (Go Windows Azure Client Library) |
|
3 |
================================================== |
|
4 |
||
5 |
(this doc is a huge WIP) |
|
6 |
||
7 |
Submitting changes |
|
8 |
------------------ |
|
9 |
||
10 |
`GWACL`_ is hosted on Launchpad using `Bazaar`_. Submitting a change |
|
11 |
requires you to create a merge proposal against the trunk branch and a |
|
12 |
core committer will then review the branch. Once the branch is accepted, |
|
13 |
it will be landed by the reviewer. |
|
14 |
||
|
122.3.3
by Julian Edwards
review comments |
15 |
All branch submissions must be formatted using ``make format``. They must |
16 |
also have a successful test run with ``make check``. New features must |
|
|
122.3.1
by Julian Edwards
add HACKING.txt and clean up README |
17 |
always be accompanied by new tests. |
18 |
||
19 |
.. _GWACL: https://launchpad.net/gwacl |
|
20 |
.. _Bazaar: http://bazaar.canonical.com/ |
|
21 |
||
22 |
||
23 |
Prerequisites |
|
24 |
------------- |
|
25 |
||
26 |
The code that communicates with Azure's management API uses *libcurl*, through |
|
|
122.3.2
by Julian Edwards
another cleanup |
27 |
a Go language binding called *go-curl*. You need to install the libcurl |
28 |
headers for your OS. On Ubuntu this is:: |
|
|
122.3.1
by Julian Edwards
add HACKING.txt and clean up README |
29 |
|
30 |
sudo apt-get install libcurl4-openssl-dev |
|
|
122.3.2
by Julian Edwards
another cleanup |
31 |
|
|
122.3.3
by Julian Edwards
review comments |
32 |
If you didn't ``go get`` gwacl you may also need to install go-curl:: |
|
122.3.2
by Julian Edwards
another cleanup |
33 |
|
|
122.3.1
by Julian Edwards
add HACKING.txt and clean up README |
34 |
go get github.com/andelf/go-curl |
35 |
||
36 |
On Ubuntu 12.10 at least, you specifically need the given version of libcurl. |
|
37 |
With other versions you will receive unexpected "403" HTTP status codes |
|
38 |
("Forbidden") from the Azure server.
|
|
39 |
||
40 |
Why use libcurl? At the time of writing, Go's built-in http package does not |
|
41 |
support TLS renegotiation. We find that Azure forces such a renegotiation |
|
42 |
when we access the management API. The use of libcurl is embedded so that |
|
43 |
future implementations can swap it out for a different http library without |
|
44 |
breaking compatibility. |
|
45 |
||
46 |
||
47 |
API philosophy |
|
48 |
-------------- |
|
49 |
||
|
122.3.3
by Julian Edwards
review comments |
50 |
API functions in the library should take a single struct parameter, which |
51 |
itself contains one or more parameters. Existing functions that do not follow |
|
52 |
this rule are historic and should not be copied. |
|
|
122.3.1
by Julian Edwards
add HACKING.txt and clean up README |
53 |
|
54 |
This brings several advantages:: |
|
55 |
||
56 |
1. Keyword parameters improve callsite readability. |
|
57 |
2. It allows for parameters to be defaulted if not supplied. |
|
58 |
3. It's much easier to change the API later without breaking existing |
|
59 |
code, it just needs re-compiling in the case where you add new, |
|
60 |
optional, parameters. |
|
61 |
||
62 |