Skip to content

Commit 214fdd8

Browse files
adamretteradamretter
authored
Merge pull request #843 from djbpitt/master
Document icon.png
2 parents ceae4a2 + 9e3c951 commit 214fdd8

File tree

1 file changed

+72
-40
lines changed
  • src/main/xar-resources/data/repo

1 file changed

+72
-40
lines changed

‎src/main/xar-resources/data/repo/repo.xml‎

Lines changed: 72 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@
2424
<title>Introduction</title>
2525

2626
<para>The package repository is based on and extends the <link condition="_blank"
27-
xlink:href="http://expath.org/modules/pkg/">EXPath Packaging System</link>. The core of
28-
the EXPath packaging specification has been designed to work across different XQuery
27+
xlink:href="http://expath.org/modules/pkg/">EXPath Packaging System</link>. The core
28+
of the EXPath packaging specification has been designed to work across different XQuery
2929
implementations and is targeted at managing extension libraries (including XQuery, Java
3030
or XSLT code modules). eXist-db extends this core by adding a facility for the automatic
3131
deployment of entire applications into the database. </para>
@@ -73,16 +73,20 @@
7373
directory: <literal>expath-pkg.xml</literal> and <literal>repo.xml</literal>:</para>
7474
<variablelist>
7575
<varlistentry>
76-
<term> <literal>expath-pkg.xml</literal> </term>
76+
<term>
77+
<literal>expath-pkg.xml</literal>
78+
</term>
7779
<listitem>
7880
<para>This is the standard EXPath descriptor as defined by the EXPath
7981
specification. It specifies the unique name of the package, lists
8082
dependencies and any library modules to register globally. See <xref
81-
linkend="sect-expathpkg"/>.</para>
83+
linkend="sect-expathpkg"/>.</para>
8284
</listitem>
8385
</varlistentry>
8486
<varlistentry>
85-
<term> <literal>repo.xml</literal> </term>
87+
<term>
88+
<literal>repo.xml</literal>
89+
</term>
8690
<listitem>
8791
<para>The eXist-db specific deployment descriptor: it contains additional
8892
metadata about the package and controls how it will be deployed into the
@@ -92,6 +96,10 @@
9296
</variablelist>
9397
<para>For library packages <literal>repo.xml</literal> is optional. However, we recommend to
9498
always provide it for better tool integration.</para>
99+
<para>The following is not mentioned in the EXPath spec, but if an image resource with the
100+
filename <literal>icon.png</literal> or <literal>icon.svg</literal> is found in the root
101+
directory of an app, the eXist-db dashboard will display that user-supplied image
102+
instead of the default eXist-db blue dotted <literal>X</literal>.</para>
95103

96104
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
97105

@@ -154,8 +162,8 @@
154162
<code>expath-pkg.xml</code> descriptor. For eaxample:</para>
155163
<programlisting language="xml" xlink:href="listings/listing-2.xml"/>
156164
<para>It is also possible to create a dependency on a specific version, based on
157-
<link condition="_blank" xlink:href="https://semver.org/">Semantic
158-
Versioning</link>. This can be done by adding either of the attributes:
165+
<link condition="_blank" xlink:href="https://semver.org/">Semantic
166+
Versioning</link>. This can be done by adding either of the attributes:
159167
<code>version</code>, <code>semver</code>, <code>semver-min</code>,
160168
<code>semver-max</code>: </para>
161169
<variablelist>
@@ -189,8 +197,8 @@
189197
<varlistentry>
190198
<term><code>semver-max</code></term>
191199
<listitem>
192-
<para>Defines a maximum version according to the
193-
<code>semver</code> scheme.</para>
200+
<para>Defines a maximum version according to the <code>semver</code>
201+
scheme.</para>
194202
</listitem>
195203
</varlistentry>
196204
</variablelist>
@@ -216,7 +224,7 @@
216224
and may be used by other packages without knowing where the module code is
217225
stored. </para>
218226
<para>For example, the following descriptor registers the module
219-
<literal>functx.xql</literal> using the given namespace: </para>
227+
<literal>functx.xql</literal> using the given namespace: </para>
220228
<programlisting language="xml" xlink:href="listings/listing-4.xml"/>
221229
<para>The namespace has to correspond to the namespace defined in the module
222230
declaration of the XQuery module. The file should be placed into a subdirectory
@@ -282,26 +290,50 @@
282290
<colspec colwidth="33%"/>
283291
<thead>
284292
<row>
285-
<entry> <para>Type of package</para> </entry>
286-
<entry> <para>type</para> </entry>
287-
<entry> <para>target</para> </entry>
293+
<entry>
294+
<para>Type of package</para>
295+
</entry>
296+
<entry>
297+
<para>type</para>
298+
</entry>
299+
<entry>
300+
<para>target</para>
301+
</entry>
288302
</row>
289303
</thead>
290304
<tbody>
291305
<row>
292-
<entry> <para>Application package</para> </entry>
293-
<entry> <para><code>application</code></para> </entry>
294-
<entry> <para>specified</para> </entry>
306+
<entry>
307+
<para>Application package</para>
308+
</entry>
309+
<entry>
310+
<para><code>application</code></para>
311+
</entry>
312+
<entry>
313+
<para>specified</para>
314+
</entry>
295315
</row>
296316
<row>
297-
<entry> <para>Resource package</para> </entry>
298-
<entry> <para><code>library</code></para> </entry>
299-
<entry> <para>specified</para> </entry>
317+
<entry>
318+
<para>Resource package</para>
319+
</entry>
320+
<entry>
321+
<para><code>library</code></para>
322+
</entry>
323+
<entry>
324+
<para>specified</para>
325+
</entry>
300326
</row>
301327
<row>
302-
<entry> <para>Library package</para> </entry>
303-
<entry> <para><code>library</code></para> </entry>
304-
<entry> <para>not specified</para> </entry>
328+
<entry>
329+
<para>Library package</para>
330+
</entry>
331+
<entry>
332+
<para><code>library</code></para>
333+
</entry>
334+
<entry>
335+
<para>not specified</para>
336+
</entry>
305337
</row>
306338
</tbody>
307339
</tgroup>
@@ -338,8 +370,8 @@
338370
<term><tag>permissions</tag></term>
339371
<listitem>
340372
<para>You can define package specific permissions in the
341-
<literal>repo.xml</literal> to use when uploading package contents like
342-
this: </para>
373+
<literal>repo.xml</literal> to use when uploading package contents
374+
like this: </para>
343375
<programlisting language="xml" xlink:href="listings/listing-9.xml"/>
344376
<para> All resources and collections will be owned by the specified user and
345377
permissions will be changed to those given in <literal>mode</literal>.
@@ -350,7 +382,7 @@
350382
automatically on all XQuery files, in addition to the default
351383
permissions defined in the descriptor. For more control over
352384
permissions, use a post-install XQuery script (see element
353-
<tag>finish</tag> below).</para>
385+
<tag>finish</tag> below).</para>
354386
<para> It is generally recommended to specify users in this manner when a
355387
package requires write privileges to the database, and to use a custom
356388
user-group (i.e. not <code>dba</code>). To avoid conflicts with locally
@@ -366,13 +398,13 @@
366398
<para>Points to an XQuery script inside the root of the package archive,
367399
which will be executed before any package data is uploaded to the
368400
database. By convention the XQuery script is called
369-
<literal>pre-install.xql</literal>, but this is not a
401+
<literal>pre-install.xql</literal>, but this is not a
370402
requirement.</para>
371403
<para>If you create a package via eXide, it will generate a default
372-
<literal>pre-install.xql</literal> which uploads the default collection
373-
configuration to the system collection. This needs to be done before
374-
deployment to guarantee that index definitions are applied when data is
375-
uploaded to the db.</para>
404+
<literal>pre-install.xql</literal> which uploads the default
405+
collection configuration to the system collection. This needs to be done
406+
before deployment to guarantee that index definitions are applied when
407+
data is uploaded to the db.</para>
376408
<para>The target collection, the file system path to the current package
377409
directory and eXist-db's home directory, are passed to the script as
378410
external variables:</para>
@@ -388,7 +420,7 @@
388420
This will be executed <emphasis>after</emphasis> all data has been
389421
uploaded to the database. It receives the same external variables as the
390422
prepare script. The convention is to name the script
391-
<literal>post-install.xql</literal>.</para>
423+
<literal>post-install.xql</literal>.</para>
392424
<para>Use the <tag>finish</tag> script to run additional tasks or move data
393425
into different collections. For example, the XQuery function
394426
documentation app runs an indexing task from the finish trigger to
@@ -434,14 +466,14 @@
434466
<title>Configuring the repository root</title>
435467

436468
<para>The root collection for deployed packages can be configured in
437-
<literal>conf.xml</literal>:</para>
469+
<literal>conf.xml</literal>:</para>
438470
<programlisting language="xml" xlink:href="listings/listing-11.xml"/>
439471
<para>The install location specified in the <tag>target</tag> element of
440-
<literal>repo.xml</literal> will always be relative to this root collection.</para>
472+
<literal>repo.xml</literal> will always be relative to this root collection.</para>
441473
<para>eXist-db's URL rewriting is by default configured to map any path starting with
442474
<code>/apps</code> to the repository root collection. Check
443-
<literal>etc/webapp/WEB-INF/controller-config.xml</literal> and the <link
444-
xlink:href="urlrewrite">URL rewriting documentation</link>.</para>
475+
<literal>etc/webapp/WEB-INF/controller-config.xml</literal> and the <link
476+
xlink:href="urlrewrite">URL rewriting documentation</link>.</para>
445477
</sect1>
446478

447479
<!-- ================================================================== -->
@@ -453,10 +485,10 @@
453485
programmatically install, remove or inspect packages. The Dashboard Package Manager
454486
relies on the same functions.</para>
455487
<para>The module distinguishes between <emphasis>installation</emphasis> and
456-
<emphasis>deployment</emphasis> steps. The reason for this distinction is: while the
488+
<emphasis>deployment</emphasis> steps. The reason for this distinction is: while the
457489
installation process is standardized by the EXPath packaging specification, the
458490
deployment step is implementation defined and specific to eXist-db.
459-
<emphasis>Installation</emphasis> will register a package with the EXPath packaging
491+
<emphasis>Installation</emphasis> will register a package with the EXPath packaging
460492
system, but not copy anything into the database. <emphasis>Deployment</emphasis> will
461493
deploy the application into the database as specified by the <literal>repo.xml</literal>
462494
descriptor.</para>
@@ -489,14 +521,14 @@
489521
distribute applications to your customers. The eXist-db repository is implemented by the
490522
application package <code>http://exist-db.org/apps/public-repo</code>. The code can be
491523
downloaded from the <link condition="_blank"
492-
xlink:href="https://github.com/eXist-db/public-xar-repo">eXist-db GitHub</link>
524+
xlink:href="https://github.com/eXist-db/public-xar-repo">eXist-db GitHub</link>
493525
repo.</para>
494526
<para>Once you have built and installed the app, you can upload the package
495527
<code>.xar</code> files you wish to distribute into the collection
496-
<literal>public-repo/public</literal>. To make the uploaded <code>.xar</code> files
528+
<literal>public-repo/public</literal>. To make the uploaded <code>.xar</code> files
497529
available, run the query <literal>public-repo/modules/update.xql</literal> once as an
498530
<code>admin</code> user. This will create a document <literal>apps.xml</literal> in
499-
<literal>public-repo/public</literal>.</para>
531+
<literal>public-repo/public</literal>.</para>
500532
</sect1>
501533

502534
</article>

0 commit comments

Comments
 (0)