This repository has been archived by the owner on May 4, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 0
/
packaging.html
345 lines (318 loc) · 22.4 KB
/
packaging.html
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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Packaging an application — Batis 0.1 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="Batis 0.1 documentation" href="index.html" />
<link rel="next" title="FAQs" href="faq.html" />
<link rel="prev" title="Installing applications" href="installing.html" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
</head>
<body role="document">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="packaging-an-application">
<h1>Packaging an application<a class="headerlink" href="#packaging-an-application" title="Permalink to this headline">¶</a></h1>
<div class="topic">
<p class="topic-title first">Packaging examples</p>
<p>There are <a class="reference external" href="https://batis-installer.github.io/example-apps/">example applications</a>
showing how to use Batis with popular technologies like Electron or PyQt.</p>
</div>
<p>You’ve got your application running smoothly, and you’re ready to invite other
people to use it. Here’s how to package it from scratch using Batis:</p>
<ol class="arabic">
<li><p class="first">Prepare a directory containing your built application, so that it can run
regardless of where the directory is located (i.e. everything inside the
application is loaded by relative paths).</p>
</li>
<li><p class="first">Add a <code class="file docutils literal"><span class="pre">batis_info</span></code> subdirectory in the top level of this application
directory. This should contain:</p>
<ul>
<li><p class="first"><code class="file docutils literal"><span class="pre">metadata.json</span></code> - a JSON object containing information about your
application, including:</p>
<ul>
<li><p class="first"><code class="docutils literal"><span class="pre">name</span></code> and <code class="docutils literal"><span class="pre">byline</span></code> - brief, human readable information about the
application, which may be displayed by tools for managing applications.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">icon_name</span></code> <em>or</em> <code class="docutils literal"><span class="pre">icon_file</span></code> - an icon for your application, which tools
for managing applications may display. <code class="docutils literal"><span class="pre">icon_name</span></code>, which is preferred,
identifies an icon from the <code class="docutils literal"><span class="pre">batis_info/icons</span></code> directory described below.
<code class="docutils literal"><span class="pre">icon_file</span></code> is a relative path to an icon file within the application
directory.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">index_url</span></code> - the URL of the application’s <a class="reference internal" href="#index-file"><span>index file</span></a>.
Future versions of Batis will use this to look for application updates.
Optional but strongly recommended.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">commands</span></code> - list of objects, each with ‘name’ and ‘target’ keys.
<code class="docutils literal"><span class="pre">target</span></code>, a path relative to the root of your application directory,
will be symlinked as <code class="docutils literal"><span class="pre">name</span></code> to a location on <span class="target" id="index-0"></span><code class="xref std std-envvar docutils literal"><span class="pre">PATH</span></code>. E.g.:</p>
<div class="highlight-python"><div class="highlight"><pre>"commands": [{"target": "bin/launch.sh", "name": "myapp"}]
</pre></div>
</div>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">format_version</span></code> - <code class="docutils literal"><span class="pre">[1,</span> <span class="pre">0]</span></code> with the details described in this
document. Future releases may increment the second number for backwards
compatible changes to the package format, and the first for incompatible
changes.</p>
</li>
</ul>
</li>
<li><p class="first"><code class="file docutils literal"><span class="pre">dependencies.json</span></code> - optional, a JSON object with details about
external packages that need to be installed for you application. See
<a class="reference internal" href="#dependencies"><span>Dependencies</span></a> for more details.</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">system_packages</span></code> - a specification of distro packages that the user
must have installed. See <a class="reference internal" href="#dependencies"><span>Dependencies</span></a> for details.</li>
<li><code class="docutils literal"><span class="pre">description</span></code> - a string listing the same distro
packages in human-readable form. This will be shown to the user if Batis
can’t automatically install the dependencies. E.g. for a PyQt application,
this could be <code class="docutils literal"><span class="pre">"Python</span> <span class="pre">3,</span> <span class="pre">PyQt5"</span></code>.</li>
</ul>
</li>
<li><p class="first"><code class="file docutils literal"><span class="pre">desktop/*.desktop</span></code> - Zero to many desktop entry files
(<a class="reference external" href="http://standards.freedesktop.org/desktop-entry-spec/latest/">spec</a>).
These can add your application to desktop menus or launchers, and associate
it with given mime types. You can use <code class="docutils literal"><span class="pre">{{INSTALL_DIR}}</span></code> inside these to
refer to your application’s directory:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">Exec</span><span class="o">=</span><span class="s">"{{INSTALL_DIR}}/bin/foo"</span> <span class="o">%</span><span class="n">F</span>
</pre></div>
</div>
</li>
<li><p class="first"><code class="file docutils literal"><span class="pre">mime/*.xml</span></code> - Zero to many mime database XML source files
(<a class="reference external" href="http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html#idm140625833214912">spec</a>,
<a class="reference external" href="http://www.freedesktop.org/wiki/Specifications/AddingMIMETutor/">tutorial</a>).
These can define new file types for your application.</p>
</li>
<li><p class="first"><code class="file docutils literal"><span class="pre">icons/</span><em><span class="pre">theme</span></em><span class="pre">/</span><em><span class="pre">size</span></em><span class="pre">x</span><em><span class="pre">size</span></em><span class="pre">/</span><em><span class="pre">category</span></em><span class="pre">/</span><em><span class="pre">name</span></em><span class="pre">.png</span></code> - icons for your
application and new mime types. Theme will normally be ‘hicolor’, which
is used as the fallback theme, and you should include hicolor variants
in addition to any other theme you want to add icons for. You should
install at least a 48x48 pixel icon; other square sizes are optional.
Category will typically be either ‘apps’ or ‘mimetype’.
(<a class="reference external" href="http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html">Icon theme spec</a>)</p>
</li>
</ul>
</li>
<li><p class="first">Use <code class="docutils literal"><span class="pre">batis</span> <span class="pre">verify</span></code> to check that all the necessary information is in
place:</p>
<div class="highlight-python"><div class="highlight"><pre>batis verify path/to/app_directory
</pre></div>
</div>
<p>Fix any problems that this reports.</p>
</li>
<li><p class="first">Pack the directory into a tarball:</p>
<div class="highlight-python"><div class="highlight"><pre>batis pack path/to/app_directory -n myapp -o myapp-0.1.app.tgz
</pre></div>
</div>
<p>This makes a gzipped tarball of the directory you’re using, and adds an
<code class="docutils literal"><span class="pre">install.sh</span></code> script, along with the necessary Batis files, so that users
without Batis can easily install your application. Upload the tarball
somewhere publicly accessible.</p>
</li>
<li><p class="first">Prepare a <a class="reference internal" href="#index-file"><span>build index file</span></a>, and make it accessible on the
web over HTTPS.</p>
</li>
</ol>
<p>You can now invite users with Batis to install your application using a link to
the index file, replacing <code class="docutils literal"><span class="pre">https://</span></code> with <code class="docutils literal"><span class="pre">batis://</span></code>. For instance:</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt"><a</span> <span class="na">href=</span><span class="s">"batis://example.com/myapp/batis_index.json"</span><span class="nt">></span>
Click to install
<span class="nt"></a></span>
</pre></div>
</div>
<p>For users without Batis installed, provide links directly to the tarballs, and
instructions to download, un-tar and run <code class="docutils literal"><span class="pre">./install.sh</span></code>.</p>
<div class="section" id="dependencies">
<span id="id1"></span><h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2>
<p>Dependencies are third party code or resources that your application uses. Batis
lets you choose whether to bundle dependencies inside your tarball, or specify
that they should be installed by a system package manager. Each has advantages:</p>
<ul class="simple">
<li>Bundled dependencies isolate you from API changes in your dependency, because
the version your code uses is fixed until you decide to update it.</li>
<li>Separately installed dependencies mean your users can benefit from security
and performance improvements in the dependencies without you needing to make a
new release. It also means your tarball is smaller.</li>
</ul>
<p>In general, I recommend that you specify only large, stable dependencies - such
as Python, Java or Qt - for external installation.</p>
<p>Different distributions use different naming schemes for packages, so the
<code class="docutils literal"><span class="pre">system_packages</span></code> field in dependencies.json is a list of possible specifications,
allowing Batis to choose one suited to the user’s distribution. For instance:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span>
<span class="p">{</span>
<span class="s">"package_manager"</span><span class="p">:</span> <span class="s">"apt-get"</span><span class="p">,</span>
<span class="s">"packages"</span><span class="p">:</span> <span class="p">[</span><span class="s">"python3"</span><span class="p">,</span> <span class="s">"python3-pyqt5"</span><span class="p">,</span> <span class="s">"python3-pyqt5.qtsvg"</span><span class="p">]</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="s">"package_manager"</span><span class="p">:</span> <span class="s">"yum"</span><span class="p">,</span>
<span class="s">"packages"</span><span class="p">:</span> <span class="p">[</span><span class="s">"python3"</span><span class="p">,</span> <span class="s">"python3-qt5"</span><span class="p">]</span>
<span class="p">}</span>
<span class="p">]</span>
</pre></div>
</div>
<p>Each specification has either a <code class="docutils literal"><span class="pre">package_manager</span></code> field or a
<code class="docutils literal"><span class="pre">distribution</span></code> field. Use <code class="docutils literal"><span class="pre">package_manager</span></code> where possible, because it’s
less specific: <code class="docutils literal"><span class="pre">"package_manager":</span> <span class="pre">"apt-get"</span></code> will work on Debian,
Ubuntu, Linux Mint, and many other derivatives. Batis recognises these
package managers:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">apt</span><span class="o">-</span><span class="n">get</span><span class="p">,</span> <span class="n">yum</span><span class="p">,</span> <span class="n">zypper</span><span class="p">,</span> <span class="n">urpmi</span><span class="p">,</span> <span class="n">pacman</span><span class="p">,</span> <span class="n">sbopkg</span><span class="p">,</span> <span class="n">equo</span><span class="p">,</span> <span class="n">emerge</span>
</pre></div>
</div>
<p>If you need to do something different for a specific distribution, run
<code class="docutils literal"><span class="pre">lsb_release</span> <span class="pre">-i</span></code> to find the name to use. Put it before the more general
specification in the list; Batis will use the first one that matches when
installing.</p>
<p>The user will be prompted for their password for sudo access to install the
necessary system packages.</p>
<p>If no specification matches, or installing the system packages fails, Batis
will ask the user to ensure the dependencies are installed. It uses the
<code class="docutils literal"><span class="pre">description</span></code> field in <code class="docutils literal"><span class="pre">dependencies.json</span></code> for this.</p>
<p>If your package doesn’t require any system packages, you can leave the
<code class="docutils literal"><span class="pre">dependencies.json</span></code> file out.</p>
</div>
<div class="section" id="the-index-file">
<span id="index-file"></span><h2>The index file<a class="headerlink" href="#the-index-file" title="Permalink to this headline">¶</a></h2>
<p>Users will install applications by pointing Batis at an index file.
This is the entry point which describes your application and points to the
available tarballs.</p>
<p>The index file must be available over HTTPS. Hosting your website on
<a class="reference external" href="https://pages.github.com/">Github Pages</a> is one easy and free way to support
HTTPS.</p>
<p>The index should be JSON, looking like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
<span class="s">"name"</span><span class="p">:</span> <span class="s">"My App"</span><span class="p">,</span>
<span class="s">"byline"</span><span class="p">:</span> <span class="s">"Easily frobulate pufoos on demand"</span><span class="p">,</span>
<span class="s">"icon_url"</span><span class="p">:</span> <span class="s">"https://example.com/myapp_logo.png"</span><span class="p">,</span>
<span class="s">"format_version"</span><span class="p">:</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span>
<span class="s">"builds"</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="s">"url"</span><span class="p">:</span> <span class="s">"https://example.com/downloads/myapp_0.1_linux_64bit.app.tar.gz"</span><span class="p">,</span>
<span class="s">"sha512"</span><span class="p">:</span> <span class="s">"48157035840[...]bd4a14146b9"</span><span class="p">,</span>
<span class="s">"version"</span><span class="p">:</span> <span class="s">"0.1"</span><span class="p">,</span>
<span class="s">"kernel"</span><span class="p">:</span> <span class="s">"Linux"</span><span class="p">,</span>
<span class="s">"arch"</span><span class="p">:</span> <span class="s">"x86_64"</span>
<span class="p">},</span>
<span class="o">...</span>
<span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="topic">
<p class="topic-title first">Checking your index</p>
<p>When you create or update your index, check that it has the necessary
information by running:</p>
<div class="highlight-python"><div class="highlight"><pre>batis verify-index <path_or_url>
</pre></div>
</div>
</div>
<p>The <code class="docutils literal"><span class="pre">name</span></code>, <code class="docutils literal"><span class="pre">byline</span></code> and <code class="docutils literal"><span class="pre">icon_url</span></code> fields are like those inside
<code class="file docutils literal"><span class="pre">metadata.json</span></code>, except that <code class="docutils literal"><span class="pre">icon_url</span></code> is a URL. These fields are
duplicated so that installer tools can display information about the application
before downloading a tarball.</p>
<p><code class="docutils literal"><span class="pre">format_version</span></code> is <code class="docutils literal"><span class="pre">[1,</span> <span class="pre">0]</span></code> with the details described here. This is for the
index format, and is not connected to the package format version stored in
<code class="docutils literal"><span class="pre">metadata.json</span></code>.</p>
<p>Batis will select an appropriate build for the user’s system from the <code class="docutils literal"><span class="pre">builds</span></code> array, based on the
<code class="docutils literal"><span class="pre">kernel</span></code> and <code class="docutils literal"><span class="pre">arch</span></code> fields. These should match the results of <code class="docutils literal"><span class="pre">uname</span> <span class="pre">-s</span></code>
and <code class="docutils literal"><span class="pre">uname</span> <span class="pre">-m</span></code> respectively, and are not case sensitive. As a special case,
<code class="docutils literal"><span class="pre">"arch":</span> <span class="pre">"x86"</span></code> will match <code class="docutils literal"><span class="pre">i386</span></code>, <code class="docutils literal"><span class="pre">i686</span></code>, and any <code class="docutils literal"><span class="pre">i<N>86</span></code>.</p>
<p>If your application doesn’t need separate builds for different kernels or
architectures—for instance, if it only contains Python code with no C extensions
—you can set these fields to “any”, or omit them entirely.</p>
<p>If there are multiple suitable builds, Batis will take the one with the highest
version number. The version number should contain one or more numeric parts,
separated by non-numeric characters such as <code class="docutils literal"><span class="pre">.</span></code>. Batis ignores any non-numeric
parts. You can use negative numbers for pre-releases (e.g. <code class="docutils literal"><span class="pre">2.0.-1.3</span></code>).</p>
<p>The preferred build will be downloaded from the URL given. HTTP URLs are allowed
here, but they must have a hash.</p>
<p>The <code class="docutils literal"><span class="pre">sha512</span></code> field is recommended if you specify an https URL, and mandatory
for http. If provided, it must match the SHA-512 hash of the tarball available
for download.</p>
<div class="topic">
<p class="topic-title first">Future extensions</p>
<p>Future versions of Batis may use extra fields in the index to download
incremental upgrades, smaller packages containing just the differences
between two versions of the application.
The index could also contain information for downloading tarballs using
peer-to-peer mechanisms like IPFS or BitTorrent.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo">
<a href="index.html">
<img class="logo" src="_static/batis-logo.png" alt="Logo"/>
<h1 class="logo logo-name">Batis</h2>
</a>
</p>
<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install-batis.html">Installing Batis</a></li>
<li class="toctree-l1"><a class="reference internal" href="installing.html">Installing applications</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Packaging an application</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a></li>
<li class="toctree-l2"><a class="reference internal" href="#the-index-file">The index file</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQs</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li>Previous: <a href="installing.html" title="previous chapter">Installing applications</a></li>
<li>Next: <a href="faq.html" title="next chapter">FAQs</a></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2015, Thomas Kluyver.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.3.1</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.6</a>
|
<a href="_sources/packaging.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>