Merge branch 'main' of github.com:propensive/adversaria

readme.md

@@ -17,9 +17,17 @@ _annotations_ in Scala, by making them available through _typeclass interfaces_.
 - no macro code is required to use annotations
 
 
-## Availability
+## Availability Plan
 
-Adversaria has not yet been published as a binary.
+Adversaria has not yet been published. The medium-term plan is to build Adversaria
+with [Fury](/propensive/fury) and to publish it as a source build on
+[Vent](/propensive/vent). This will enable ordinary users to write and build
+software which depends on Adversaria.
+
+Subsequently, Adversaria will also be made available as a binary in the Maven
+Central repository. This will enable users of other build tools to use it.
+
+For the overeager, curious and impatient, see [building](#building).
 
 ## Getting Started
 
@@ -92,6 +100,7 @@ accessor, such as `_.email`, otherwise the method will not compile.
 
 
 
+
 ## Status
 
 Adversaria is classified as __fledgling__. For reference, Scala One projects are
@@ -103,26 +112,62 @@ categorized into one of the following five stability levels:
 - _dependable_: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version `1.0.0` or later
 - _adamantine_: proven, reliable and production-ready, with no further breaking changes ever anticipated
 
-Projects at any stability level, even _embryonic_ projects, are still ready to
-be used, but caution should be taken if there is a mismatch between the
-project's stability level and the importance of your own project.
+Projects at any stability level, even _embryonic_ projects, can still be used,
+as long as caution is taken to avoid a mismatch between the project's stability
+level and the required stability and maintainability of your own project.
 
 Adversaria is designed to be _small_. Its entire source code currently consists
 of 156 lines of code.
 
 ## Building
 
-Adversaria can be built on Linux or Mac OS with [Fury](/propensive/fury), however
-the approach to building is currently in a state of flux, and is likely to
-change.
+Adversaria will ultimately be built by Fury, when it is published. In the
+meantime, two possibilities are offered, however they are acknowledged to be
+fragile, inadequately tested, and unsuitable for anything more than
+experimentation. They are provided only for the necessity of providing _some_
+answer to the question, "how can I try Adversaria?".
+
+1. *Copy the sources into your own project*
+
+   Read the `fury` file in the repository root to understand Adversaria's build
+   structure, dependencies and source location; the file format should be short
+   and quite intuitive. Copy the sources into a source directory in your own
+   project, then repeat (recursively) for each of the dependencies.
+
+   The sources are compiled against the latest nightly release of Scala 3.
+   There should be no problem to compile the project together with all of its
+   dependencies in a single compilation.
+
+2. *Build with [Wrath](https://github.com/propensive/wrath/)*
+
+   Wrath is a bootstrapping script for building Adversaria and other projects in
+   the absence of a fully-featured build tool. It is designed to read the `fury`
+   file in the project directory, and produce a collection of JAR files which can
+   be added to a classpath, by compiling the project and all of its dependencies,
+   including the Scala compiler itself.
+
+   Download the latest version of
+   [`wrath`](https://github.com/propensive/wrath/releases/latest), make it
+   executable, and add it to your path, for example by copying it to
+   `/usr/local/bin/`.
+
+   Clone this repository inside an empty directory, so that the build can
+   safely make clones of repositories it depends on as _peers_ of `adversaria`.
+   Run `wrath -F` in the repository root. This will download and compile the
+   latest version of Scala, as well as all of Adversaria's dependencies.
+
+   If the build was successful, the compiled JAR files can be found in the
+   `.wrath/dist` directory.
 
 ## Contributing
 
-Contributors to Adversaria are welcome and encouraged. New contributors may like to look for issues marked
-<a href="https://github.com/propensive/adversaria/labels/beginner">beginner</a>.
+Contributors to Adversaria are welcome and encouraged. New contributors may like
+to look for issues marked
+[beginner](https://github.com/propensive/adversaria/labels/beginner).
 
-We suggest that all contributors read the [Contributing Guide](/contributing.md) to make the process of
-contributing to Adversaria easier.
+We suggest that all contributors read the [Contributing
+Guide](/contributing.md) to make the process of contributing to Adversaria
+easier.
 
 Please __do not__ contact project maintainers privately with questions unless
 there is a good reason to keep them private. While it can be tempting to
@@ -131,25 +176,33 @@ audience, and it can result in duplication of effort.
 
 ## Author
 
-Adversaria was designed and developed by Jon Pretty, and commercial support and training is available from
-[Propensive O&Uuml;](https://propensive.com/).
+Adversaria was designed and developed by Jon Pretty, and commercial support and
+training on all aspects of Scala 3 is available from [Propensive
+O&Uuml;](https://propensive.com/).
 
 
 
 ## Name
 
 _Adversaria_ are miscellaneous collections of notes or _annotations_, after which the library is named.
 
-In general, Scala One project names are always chosen with some rationale, however it is usually
-frivolous. Each name is chosen for more for its _uniqueness_ and _intrigue_ than its concision or
-catchiness, and there is no bias towards names with positive or "nice" meanings—since many of the
-libraries perform some quite unpleasant tasks.
+In general, Scala One project names are always chosen with some rationale,
+however it is usually frivolous. Each name is chosen for more for its
+_uniqueness_ and _intrigue_ than its concision or catchiness, and there is no
+bias towards names with positive or "nice" meanings—since many of the libraries
+perform some quite unpleasant tasks.
 
-Names should be English words, though many are obscure or archaic, and it should be noted how
-willingly English adopts foreign words. Names are generally of Greek or Latin origin, and have
-often arrived in English via a romance language.
+Names should be English words, though many are obscure or archaic, and it
+should be noted how willingly English adopts foreign words. Names are generally
+of Greek or Latin origin, and have often arrived in English via a romance
+language.
+
+## Logo
+
+The logo is an [arobase](https://en.wikipedia.org/wiki/At_sign) or "at-sign", being the Scala (and Java) symbol which introduces an annotation.
 
 ## License
 
-Adversaria is copyright &copy; 2023 Jon Pretty & Propensive O&Uuml;, and is made available under the
-[Apache 2.0 License](/license.md).
+Adversaria is copyright &copy; 2024 Jon Pretty & Propensive O&Uuml;, and
+is made available under the [Apache 2.0 License](/license.md).
+

src/core/adversaria.scala

@@ -1,5 +1,5 @@
 /*
-    Adversaria, version [unreleased]. Copyright 2023 Jon Pretty, Propensive OÜ.
+    Adversaria, version [unreleased]. Copyright 2024 Jon Pretty, Propensive OÜ.
 
     The primary distribution site is: https://propensive.com/
 

src/test/tests.scala

@@ -1,5 +1,5 @@
 /*
-    Adversaria, version [unreleased]. Copyright 2023 Jon Pretty, Propensive OÜ.
+    Adversaria, version [unreleased]. Copyright 2024 Jon Pretty, Propensive OÜ.
 
     The primary distribution site is: https://propensive.com/