Wyrm Requirements First Draft

.gitignore

@@ -0,0 +1,5 @@
+build*
+.vscode
+.cache
+.DS_Store
+

CMakeLists.txt

@@ -0,0 +1,65 @@
+cmake_minimum_required(VERSION 3.13.4)
+project(wyrm VERSION 0.0.1 LANGUAGES C CXX)
+
+# find_package(LLVM REQUIRED CONFIG)
+
+# This is intended to be the canoncial version requirement documentation. All
+# other references to this version should key off of this setting, so that it
+# doesn't have to be duplicated everywhere for up-to-date documentation.
+set(WYRM_LLVM_VERSION_REQ 15.0.6 CACHE STRING "Wyrm required LLVM version.")
+
+#if (NOT LLVM_PACKAGE_VERSION VERSION_EQUAL ${WYRM_LLVM_VERSION_REQ})
+#  message(FATAL_ERROR "Wyrm requires LLVM version ${WYRM_LLVM_VERSION_REQ}, but detected version ${LLVM_PACKAGE_VERSION}")
+#endif()
+
+#message(STATUS "Found LLVM ${LLVM_PACKAGE_VERSION}")
+#message(STATUS "Using LLVMConfig.cmake in ${LLVM_DIR}")
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED)
+
+if(EXISTS "${CMAKE_SOURCE_DIR}/.git")
+  execute_process(
+      COMMAND git rev-parse --abbrev-ref HEAD
+      WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+      OUTPUT_VARIABLE WYRM_GIT_BRANCH
+      OUTPUT_STRIP_TRAILING_WHITESPACE
+  )
+  execute_process(
+      COMMAND git log -1 --format=%h
+      WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+      OUTPUT_VARIABLE WYRM_GIT_COMMIT_HASH
+      OUTPUT_STRIP_TRAILING_WHITESPACE
+  )
+else()
+  set(WYRM_GIT_BRANCH "not_a_git_checkout")
+  set(WYRM_GIT_COMMIT_HASH "na")
+endif()
+
+message(STATUS "wyrm v${PROJECT_VERSION}, ${WYRM_GIT_BRANCH}@${WYRM_GIT_COMMIT_HASH}")
+configure_file(README.md.in "${PROJECT_SOURCE_DIR}/README.md")
+
+option(WYRM_DOCS "Build documentation using sphinx." ON)
+
+include_directories(${CMAKE_CURRENT_SOURCE_DIR})
+
+if (WYRM_DOCS)
+  find_program(SPHINX_BUILD sphinx-build REQUIRED)
+  if (NOT SPHINX_BUILD)
+    message(FATAL_ERROR "Wyrm documentation requires Sphinx.")
+  endif()
+
+  file(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/docs/html")
+  file(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/docs/cache")
+  configure_file(docs/conf.py.in "${PROJECT_BINARY_DIR}/docs/conf.py")
+
+  add_custom_target(wyrm_docs ALL
+    COMMAND ${SPHINX_BUILD}
+      -b html -d "${PROJECT_BINARY_DIR}/docs/cache"
+      -j auto
+      -c "${PROJECT_BINARY_DIR}/docs/"
+      "${PROJECT_SOURCE_DIR}/docs/"
+      "${PROJECT_BINARY_DIR}/docs/html"
+    VERBATIM
+  )
+endif()

README.md

@@ -1,2 +1,34 @@
-# wyrm
-LLVM-based realtime dsp language
+
+[comment]: # (Generated file, make edits to README.md.in)
+
+![wyrm logo](docs/static/images/wyrm_logo.png)
+
+# WYRM
+
+Wyrm is an experimental programming language for creative media production.
+Wyrm is a statically-typed, garbage-collected language based on LLVM. Wyrm is
+in the early development/prototype stage and is not yet ready for use.
+
+## Compiling Quick Start
+
+Wyrm depends on LLVM to compile. The easiest way to get LLVM is to download the
+binaries from [llvm.org](https://llvm.org). Wyrm requires LLVM version
+15.0.6, and will not compile against another version. Download
+and extract the matching version of LLVM binaries. Provide the path to the CMake
+build system with the `LLVM_DIR` variable, like:
+
+```
+mkdir build
+cd build
+cmake -G Ninja -DLLVM_DIR=<path_to_llvm_download> ..
+cmake --build .
+```
+
+For detailed build instructions, consult the Developer Documentation either
+[in this repository](docs/developer/compiling_wyrm.rst) or
+[on the web](https://wyrm.sh/developer/compiling_wyrm.html)
+
+## Documentation
+
+Wyrm uses [sphinx](https://www.sphinx-doc.org/en/master/index.html) to generate
+the static HTML website hosted at [wyrm.sh](https://wyrm.sh).

README.md.in

@@ -0,0 +1,34 @@
+
+[comment]: # (Generated file, make edits to README.md.in)
+
+![wyrm logo](docs/static/images/wyrm_logo.png)
+
+# WYRM
+
+Wyrm is an experimental programming language for creative media production.
+Wyrm is a statically-typed, garbage-collected language based on LLVM. Wyrm is
+in the early development/prototype stage and is not yet ready for use.
+
+## Compiling Quick Start
+
+Wyrm depends on LLVM to compile. The easiest way to get LLVM is to download the
+binaries from [llvm.org](https://llvm.org). Wyrm requires LLVM version
+@WYRM_LLVM_VERSION_REQ@, and will not compile against another version. Download
+and extract the matching version of LLVM binaries. Provide the path to the CMake
+build system with the `LLVM_DIR` variable, like:
+
+```
+mkdir build
+cd build
+cmake -G Ninja -DLLVM_DIR=<path_to_llvm_download> ..
+cmake --build .
+```
+
+For detailed build instructions, consult the Developer Documentation either
+[in this repository](docs/developer/compiling_wyrm.rst) or
+[on the web](https://wyrm.sh/developer/compiling_wyrm.html)
+
+## Documentation
+
+Wyrm uses [sphinx](https://www.sphinx-doc.org/en/master/index.html) to generate
+the static HTML website hosted at [wyrm.sh](https://wyrm.sh).

docs/conf.py.in

@@ -0,0 +1,38 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Wyrm'
+copyright = '2022-2023, Lucile Rose Nihlen'
+author = 'Lucile Rose Nihlen'
+version = '@PROJECT_VERSION@'
+release = 'v@PROJECT_VERSION@ @GIT_COMMIT_HASH@'
+
+rst_prolog = """
+.. |wyrm_llvm_version_req| replace:: @WYRM_LLVM_VERSION_REQ@
+"""
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+from better import better_theme_path
+html_theme_path = [better_theme_path]
+html_theme = 'better'
+
+html_static_path = ['@PROJECT_SOURCE_DIR@/docs/static']
+html_short_title = "Home"
+html_sidebars = {
+    '**': ['localtoc.html', 'sourcelink.html', 'searchbox.html'],
+}

docs/developer/compiling_wyrm.rst

@@ -0,0 +1,45 @@
+Compiling Wyrm
+##############
+
+Prerequisites
+*************
+
+Like LLVM, we use CMake to generate our local build system and Sphinx to
+generate documentation.
+
+Downloading LLVM
+================
+
+Wyrm depends on LLVM libraries. As LLVM does not offer a stable API, we require
+a specific version of LLVM, currently |wyrm_llvm_version_req|.
+
+The release binaries for LLVM are available for download from the
+`releases page <https://releases.llvm.org/>`_ on llvm.org. Download the
+appropriate binaries for your operating system and extract them to a directory
+outside the Wyrm repository.
+
+Compiling LLVM From Source
+==========================
+
+It's also possible to build LLVM from sources, install the libraries somewhere,
+and provide that path to Wyrm during configuration.
+
+.. warning:
+  LLVM builds are compute and storage intensive. Even on powerful computers,
+  builds can take significant time.
+
+See the `LLVM CMake Build Instructions <https://llvm.org/docs/CMake.html>`_ for
+details about building LLVM with CMake. ``-DCMAKE_INSTALL_PREFIX=<path>``.
+
+
+Building The Documentation
+**************************
+
+Prerequisites
+=============
+
+``pip install sphinx-better-theme``
+
+``cmake -DWYRM_DOCS=On ..``
+
+Then the docs build with CMake automatically, appearing in ``build/doc/html``.

docs/developer/index.rst

@@ -0,0 +1,12 @@
+Developer Documentation
+=======================
+
+This section contains documentation about developing the Wyrm application,
+such as instructions about how to compile Wyrm. For details about the Wyrm
+programming language, consult the :Language Documentation:`language/index`.
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Contents:
+
+  compiling_wyrm

docs/index.rst

@@ -0,0 +1,23 @@
+.. image:: static/images/wyrm_logo.png
+  :width: 100%
+  :alt: Wyrm Logo
+
+Wyrm
+####
+
+Wyrm is an experimental audio and video synthesis language for real-time
+music and video performance.
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Contents:
+
+  developer/index
+  language/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/language/index.rst

@@ -0,0 +1,12 @@
+Language Documentation
+======================
+
+This section contains reference and tutorial content about Wyrm.
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Contents:
+
+  wyrm_requirements
+  design_document
+

docs/language/wyrm_requirements.rst

@@ -0,0 +1,52 @@
+Wyrm Requirements and Specifications
+####################################
+
+Summary
+*******
+
+Wyrm:
+  * is :ref:`statically typed <static-typing>`
+  * has automatic garbage collection
+  * supports both Ahead-of-Time (AoT) and Just-In-Time (JIT) compilation
+
+    * can generate standalone and redistributable binaries
+
+  * has multi-threaded and asynchronous execution models
+  * has robust support for object-oriented programming, including:
+
+    * compile-time enforcement of encapsulation (public and private members)
+    * multiple inheritance
+    * reflection
+    * namespaces
+
+  * supports Digital Signal Processing (DSP) with:
+
+    * a generic programming system to allow expressive type programming with
+      functional units
+    * LLVM-backed optimization of DSP code supporting vectorization,
+      inlining, loop unrolling, and others
+    * generation of both CPU and GPU instructions from the same source code
+
+  * prioritizes interoperability by:
+
+    * allowing any C ABI compiled code to call and be called by Wyrm code
+    * loading static and dynamic shared objects at runtime
+    * providing limited parsing of C and C++ header files
+
+  * supports robust diagnostics, including profiling and debugging
+  * runs on any platform supported by LLVM, including:
+
+    * Linux and other Unixes
+    * macOS
+    * Windows
+    * Bare-metal embedded platforms
+
+Detailed Discussion
+*******************
+
+.. _static-typing:
+
+Static Typing
+=============
+
+