1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
<!--
HACKING.md
Copyright 2013 Canonical Ltd.
This work is licensed under the Creative Commons Attribution-Share Alike 3.0
Unported License. To view a copy of this license, visit
http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative
Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.
-->
# Juju GUI Charm Development #
## Contacting the Developers ##
Hi. Thanks for looking at the charm. If you are interested in helping us
develop, we'd love to hear from you. Our developer-oriented discussions
happen on Freenode's IRC network in the #juju-gui channel, and you can also
join [the GUI developers mailing list](https://lists.ubuntu.com/mailman/listinfo/juju-gui).
## Getting Started ##
First, you need a configured Juju environment: see the Juju docs about
[getting started](https://juju.ubuntu.com/docs/getting-started.html). If you
do not yet have an environment defined, the Jitsu command "setup-environment"
is an easy way to get started.
You'll also need some dependencies and developer basics.
sudo apt-get install build-essential bzr libapt-pkg-dev python-pip \
python-virtualenv xvfb
Next, you need the bzr branch. We work from
[lp:~juju-gui/charms/precise/juju-gui/trunk](https://code.launchpad.net/~juju-gui/charms/precise/juju-gui/trunk).
You could start hacking now, but there's a bit more to do to prepare for
running and writing tests.
We use the juju-test test command to run our functional and unit tests. At the
time of this writing it is not yet released. To run it you must first install
it locally, e.g.:
bzr checkout --lightweight lp:juju-plugins
ln -s juju-plugins/plugins/juju_test.py juju-test
export PATH="$PATH":`pwd`
Alternatively you may check out lp:juju-plugins and link
"juju-plugins/plugins/juju_test.py" as "juju-test" somewhere in your PATH, so
that it is possible to execute "juju-test".
Before being able to run the suite, test requirements need to be installed
running the command:
make
The command above will create a ".venv" directory inside "juju-gui/tests/",
ignored by DVCSes, containing the development virtual environment with all the
testing dependencies. Run "make help" to see all the available make targets.
Now you are ready to run the functional and unit tests (see the next section).
## Testing ##
There are two types of tests for the charm: unit tests and functional tests.
Long story short, to run all the tests:
make test JUJU_ENV="myenv"
In the command above, "myenv" is the juju environment, as it is specified in
your `~/.juju/environments.yaml`, that will be bootstrapped before running the
tests and destroyed at the end of the test run.
Please read further for additional details.
### Unit Tests ###
The unit tests do not require a functional Juju environment, and can be run
with this command::
make unittest
Unit tests should be created in the "tests" subdirectory and be named in the
customary way (i.e., "test_*.py").
### Functional Tests ###
Running the functional tests requires a Juju testing environment as provided
by the juju-test command (see "Getting Started", above).
To run only the functional tests:
make ftest JUJU_ENV="myenv"
As seen before, "myenv" is the juju environment, as it is specified in your
`~/.juju/environments.yaml`, that will be bootstrapped before running the
tests and destroyed at the end of the test run.
#### LXC ####
Unfortunately, we have not found LXC-based Juju environments to be reliable
for these tests. At this time, we recommend using other environments, such as
OpenStack; but we will periodically check the tests in LXC environments
because it would be great to be able to use it. If you do want to use LXC,
you will need to install the `apt-cacher-ng` and `lxc` packages. Also note
that at this time juju-core does not support the local provider.
## Running the Charm From Development ##
If you have set up your environment to run your local development charm,
deploying the charm fails if attempted after the testing virtualenv has been
created: juju deploy exits with an error due to ".venv" directory containing
an absolute symbolic link. There are two ways to work around this problem.
The first one is running "make clean" before deploying the charm:
make clean
juju bootstrap
juju deploy --repository=/path/to/charm/repo local:precise/juju-gui
juju expose juju-gui
The second one is just running "make deploy":
juju bootstrap
make deploy
The "make deploy" command creates a temporary Juju repository (excluding
the ".venv" directory), deploys the Juju GUI charm from that repository and
exposes the juju-gui service. Also note that "make deploy" does not require
you to manually set up a local Juju environment, and preserves, if already
created, the testing virtualenv.
Now you are working with a test run, as described in
<https://juju.ubuntu.com/docs/write-charm.html#test-run>. The
`juju debug-hooks` command, described in the same web page, is your most
powerful tool to debug.
When something goes wrong, on your local machine run
`juju debug-hooks juju-gui/0` or similar. This will initially put you on the
unit that has the problem. You can look at what is going on in
`/var/lib/juju/units/[NAME OF UNIT]`. There is a charm.log file to
investigate, and a charm directory which contains the charm. The charm
directory contains the `juju-gui` and `juju` directories, so everything you
need is there.
If juju recognized an error (for instance, the unit is in an "install-error"
state) then you can do more. In another terminal on your local machine, run
`juju resolved --retry`. Then return to the debug-hooks terminal. You will
see that your exploration work has been replaced, and you are simply in the
charms directory. At the bottom of the terminal, you will see "install" as
part of the data that the debug-hooks machinery (via byobu) shows you. You
are now responsible for running the install hook. For instance, in this case,
you would run
./hooks/install
You can then watch what is going on. If something goes wrong, fix it and try
it again. Juju will not treat the hook as complete until you end the session
(e.g. CTRL-D). At that point, Juju will treat the hook as successful, and
move on to the next stage. Since you are in debug-hooks mode still, you will
be responsible for running that hook too! Look at the bottom of the terminal
to see what hook you are supposed to run.
All of this is described in more detail on the Juju site: this is an
introduction to the process.
|