::::::::::::::::::::::::::::::::::::::::::::::::::::

  AXSS
  AXSS
  AXSS

  ARES
    XANADU
      SYSTEM
        SERVER

::::::::::::::::::::::::::::::::::::::::::::::::::::

  VERSION 2.0.0

::::::::::::::::::::::::::::::::::::::::::::::::::::

  Nanite Systems Consumer Products
  Eisa City, Eisa

::::::::::::::::::::::::::::::::::::::::::::::::::::


----------------------------------------------------
 CONTENTS
----------------------------------------------------

  1. What's In The Box?
  2. Quick Setup Guide
  3. Differences From Classic Xanadu Package Service
  4. The Facet HUD
  5. Bundled Packages
  6. Creating New Packages
  7. Getting More Help
  8. Update History

----------------------------------------------------
 1. What's In The Box?
----------------------------------------------------

Your AXSS (ARES Xanadu System Server) package contains the following:

AX Server Instructions
  This document.

facet-1.0.1
  The control HUD for AXSS.

axss-2.0.0
  The actual AX server object. (Xanadu 8600/AX 040)

The AX server comes preloaded with several software packages. See Chapter 5: Bundled Packages for details.

Please note that this is not a mirror of the official NS package servers. AX servers are meant to be used by developers and communities to distribute their own work. Commercial packages, including OS updates, can only be distributed from servers owned by their creators.

----------------------------------------------------
 2. Quick Setup Guide
----------------------------------------------------

1. Rez the AX server object on land with sandbox (public rezzing) privileges.
2. Attach the Facet HUD.
3. Click the AX server object. The Facet HUD will automatically connect.
4. Click 'Change Server Name' and enter a unique name for your server. It may not contain spaces. It should be in the format 'ax<string>:<number>', where <string> and <number> are custom signifiers, e.g. axbob:0. By convention, <number> should be 0 unless the server is a mirror or continuation of a server ending in :0. Splitting up large package collections across multiple servers is one way of avoiding out-of-memory errors in the ax client.
5. Turn on 'Publish Online' if you wish the server to appear on this page: http://support.nanite-systems.com/?id=3410 This will make your ownership and the location of your server public knowledge. Entries take 1 hour to remove.
6. Turn on 'Browsable Online' if you wish to run an HTTP server to list the contents also.
7. Set 'Access Mode' to 'Private' if you wish the server to limit users to wearers of tags from a particular group. Non-eligible users will still be able to see the server, but no packages will be available for download when they actually connect.
8. Turn on 'Public Drop' if you wish to allow anyone to add packages to the server. Public Drop mode cannot filter uploaders, so we recommend keeping this disabled on your primary server.
9. To connect to your server, you need to run the '@ax connect <UUID>' command that it lists when you click it. This allows you to see packages on it and download them. As of ARES Beta 2, package servers are not really browsed individually by the ax client, but rather added or removed from a list of trusted sources, which simplifies the user experience.

----------------------------------------------------
 3. Differences from Classic Xanadu Service
----------------------------------------------------

3.1. Description of XPS

The original Xanadu package system was devised in 2015 with the intention of providing a user experience similar to app stores on mobile phones. The actual functionality of packages and package installation was fool-proofed to reduce points of failure. The main package firmware script (_xanadu-package) had one job: to copy all the package contents into the unit's user memory. The package manager script (_xanadu-client) on the unit was responsible for parsing manifest files (~ files) to identify what versions of packages were installed and to remove any files during deletion or upgrade.

With such a simple design, points of failure were fewer during installation, but they tended to crop up later; a new OS version might contain a bad package manager that rendered further updates impossible, or a package manifest missing a file would leave it behind. Some versions of Companion included several copies of certain files (e.g. d_rafael) because they were not listed properly in manifests, and no mechanism existed to clear out old files prior to copying them.

There was also no room for innovation. It was not possible to automatically install or clean up settings associated with a package, nor to use packages unless the unit first initiated interaction with a package server. Workarounds for some of these problems were eventually developed, but the merits of the robust package system were still frequently beset by bugs in new updates, and no amount of safeguarding could actually prevent a malicious LSL script from behaving badly if it truly wished.

XPS servers were responsible for evaluating the list of packages on the client and providing a list of available upgrades; this could create a bottleneck if many clients were attempting to access the same server at once. They also would not list a package unless it had an accompanying _info file. XPS servers also had to store all metadata in memory using bulky LSL lists, which severely limited the number of packages they could handle. As a result it was not possible for them to retain old versions of software unless the server itself was an early version.

3.2. Description of AXSS

The AX system does not directly deliver standalone package objects except for OS updates. Instead, the unit downloads a script (.pkg) which asks for a package archive (.ax.parc) payload whenever files are to be installed. The .pkg script is a native ARES shell script (i.e., an .as file) parsed by _exec that has the freedom to do whatever it needs to, allowing for custom logic to be added, such as preparation prior to installation, cleanup, help file parsing, assertions that prerequisites and dependencies have been met, or even switching between multiple package archives as needed.

The package firmware script, __parc, is also more intelligent. It can be given instructions to receive new files, making it possible to automate the most tedious part of the deployment testing process. It also attaches onto the unit's HUD, providing a play-by-play view of the installation process via a scrolling hovertext display.

Under the hood, the actual server appliances between XPS and AXSS are somewhat different, although they both perform the same main function of identifying the latest version of a file and providing it when asked. Every message in the AX family of protocols begins with a unique handle, allowing multiple users to interact with ax on the same unit simultaneously without conflict. Since AX packages store all metadata inside .pkg files with the actual .parc objects being optional, packages are always accessible even if they are poorly documented.

Although AX is much more complex than XPS, its complexities are used as a form of validation for the viability of the whole ARES system, which prevents bad versions of packages from being shipped, including OS updates. If the .pkg file fails to mention one of the files inside its archive, for example, this will be apparent immediately upon install rather than only upon removal. If a new change to the package manager introduces bugs, then it will not be possible for NS to distribute new OS updates. If the _exec program is overloaded with features, then there will not be enough memory to run scripts. This web of dependencies ensures that many of the mistakes that plagued Companion users cannot occur.

3.3. Package variants

XPS had two package types:

 - The standard _xanadu-package format (described above)
 - The __system-updater format, which was more intelligent and could dispatch assistant scripts (__system-eraser-root and __system-eraser-program) to remove hardcoded filenames. This was used exclusively for first-party products that needed access to the unit's root storage (system memory/link 1), such as OS updates and extensions.

AXSS so far has four package types:

 - .ax.parc (__parc), which is a passive data storage device that accepts a wide range of commands from the package manager
 - .sparc (__sparc), which is an automatic installer that dispatches assistant scripts (__sparc-d) to remove old files and upgrade the database, sometimes multiple times
 - .xparc (__xparc), a variation on .sparc that provides a wizard-like interactive setup process
 - .dparc (__dparc), a variation on .ax.parc that sends package data to a different storage location provided by an attached light bus device

This distribution of AXSS includes a sample package, sample-2.0.1.ax.parc, which can be used to create standard packages. See Chapter 6: Creating New Packages for basic instructions.

----------------------------------------------------
 4. The Facet HUD
----------------------------------------------------

The Facet Property Inspector is a skinnable, graphical alternative to typical dialog menus. It provides fewer buttons (only 7) per screen, but each button can hold more text or display an image. Facet menus are simpler to create than dialogs, as the functions of each button is specified when the menu is created: the programmer does not need to create additional listeners for textbox input, for example. It also provides widgets for displaying colors and fraction values (progress bars), and an interface for inputting colors.

Facet was originally created in 2017 to support the NS Power Distribution Service, but remained unreleased and incomplete until the release of AXSS. It will be used to administer other upcoming NS products, such as the next version of Telos, the ANav server, and future updates to XNMS domain appliances.

To use Facet, simply attach it and click on the server you wish to administer. You must own the server to administer it.

Facet and AXSS are both supported by AV-CAPS (http://nanite-systems.com/reports/caps.txt). If you have a working AV-CAPS Host, then it will automatically attempt to attach the Facet HUD whenever you click a compatible appliance.

Developer information on Facet is available at http://develop.nanite-systems.com/facet

----------------------------------------------------
 5. Bundled Packages
----------------------------------------------------

The following packages are included with AXSS. They may be freely modified and redistributed under the terms of the ASCL-II or ASCL-III licenses, depending on package. See Chapter 5: Bundled Packages for details. http://nanite-systems.com/ASCL for details.

  define-1.1.0: Look up the first paragraph of text from any MediaWiki article (Wikipedia, Fandom, etc.)
  fortune-0.2.4: Display a message of the day from the standard Linux fortune files (requires a server connection)
  land-0.2.0: Returns various interesting data about the parcel and region, useful for scripting
  lslisp-0.2.4: LSLisp programming language (see http://develop.nanite-systems.com/?id=2225)
  mail-1.1.0: Sends e-mail
  mantra-1.0.1: Hypnosis simulator
  news-0.2.1: Displays RSS and Atom headlines as alerts in the ARES interface
  sample-2.0.1: Instructions for how to build your own package
  saver-1.0.1: Various screen savers
  scidb-0.2.0: Look up info in scientific databases
  tell-1.2.0: Send a message to any object in the region on a specific channel
  type-1.1.0: Display the contents of a text file

----------------------------------------------------
 6. Creating New Packages
----------------------------------------------------

Once you have set up your server and connected to it (see Chapter 3: Quick Start Guide), download and install the sample package:

  @ax download sample-2.0.1.pkg
  @do sample-2.0.1.pkg install

Then read the package creation guide:

  @type package-creation-guide.txt

----------------------------------------------------
 7. Getting More Help
----------------------------------------------------

Volunteer support in the Nanite Systems User Group for this product is limited due to its niche base. Please send a notecard directly to rhet0rica for assistance, or post in #advanced-support on the NSCP Patreon Discord (https://www.patreon.com/nscp).

----------------------------------------------------
 8. Update History
----------------------------------------------------

2.0.0 (2024-06-08): Initial release.