Echoes of the Wasteland Library Development

These are the steps we take to develop the Echoes of Wasteland library.

Having the documentation part of things figured out over here now we can set up for coding!

ToDo: rdd13r - document all this from Anominous and Lugary boxes plase.

Local Box Setup Overview

We use:

GitHub Actions for build, test, deploy and publish pipelines;
Oh, My Zsh for shell configuration and plugin management;
SDK Man for local JVM SDKs and JVM language dependencies:
- Gradle software project definition manifest;
- JDK LTS for Java compiler;
- (Optional) Kotlin for Kotlin compiler;
asdf for local SDKs, i.e., Ruby, Jekyll, and dependencies:
- Ruby for Jekyll and Bundler;
- Jekyll for GitHub Pages;
- Bundler for local site development;
Conda for AI/ML component development:
- Python for native Python SDKs and environment management;
(Optional) Volta for TypeScript and Node.js UI/UX development:
- Node.js for managed Node runtime;
- Yarn for a nicer package manager;
(Optional) Docker for proper local containerization and canned builders;
- Docker Desktop the preferred distribution with classes, labs and workspaces;
- Colima for an alternative provisioning of Linux kernel and event k8s as well. *

Ops!

Automation is a critical part of our manifest because nobody wants to tinker with stuff manually. We are using GitHub Actions to automate Ops. This doesn’t affect the project manifest itself, which the Ops use to build the site. Actions live in the .github/workflows folder and are triggered by the GitHub Actions hooks. Look to familiarize yourself with the workflows we make.

Local Shell Setup

Shell is our primary IDE as it has always been. Interpreter is zsh by default (zsh --version). The plugin manager is Oh My Zsh (oh-my-zsh])

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

(Optional) Local Configuration Optimization

To understand how the startup files work look here..

We optimize by separating concerns like this:

.zshprofile: local user commons for all shells:

# Eventual Example!
eval "$(/opt/homebrew/bin/brew shellenv)"
source $(brew --prefix)/opt/asdf/libexec/asdf.sh

# Added by Toolbox App
export PATH="$PATH:/Users/YerName/Library/Application Support/JetBrains/Toolbox/scripts"

.zshenv: local user state parameters and values:

# Eventual Example!
export GITHUB_TOKEN="ghp_YerCoolToken"
export DOCKER_TOKEN="dckr_pat_YerCoolDockerToken"
export QODANA_TOKEN="YerCoolQodanaToken"

# YerCool's personal SDK stuff
export VOLTA_HOME="$HOME/.volta"
export KREW_HOME="$HOME/.krew"
export RUBYOPT="-E utf-8:utf-8"

export PATH="$HOME/bin:$VOLTA_HOME/bin:$KREW_HOME/bin:$HOME/.local/bin:$PATH"

# export MANPATH="/usr/local/man:$MANPATH"
export LANG=en_US.UTF-8
export ARCHFLAGS="-arch arm64"

#THIS MUST BE AT THE END OF THE FILE FOR SDKMAN TO WORK!!!
export SDKMAN_DIR="$HOME/.sdkman"
export SDKMAN="$SDKMAN_DIR/bin"

.zshrc: local user shell configuration - terminal step:

# Eventual Example!
# OhMyZsh generated and configured part skipped
# ...
 
zstyle ':omz:update' mode auto      # update automatically without asking
zstyle ':omz:update' frequency 1
# Example plugins chosen
plugins=(asdf brew docker docker-compose gh git gradle kubectl kubectx kube-ps1 mvn node rsync sdk sudo volta yarn conda-zsh-completion)

FPATH="$(brew --prefix)/share/zsh/site-functions:${FPATH}"
source $ZSH/oh-my-zsh.sh

# >>> conda initialize >>>
# !! Contents within this block are managed by 'conda init' !!
__conda_setup="$('/Users/rdd13r/anaconda3/bin/conda' 'shell.zsh' 'hook' 2> /dev/null)"
if [ $? -eq 0 ]; then
    eval "$__conda_setup"
else
    if [ -f "/Users/YerName/anaconda3/etc/profile.d/conda.sh" ]; then
        . "/Users/YerName/anaconda3/etc/profile.d/conda.sh"
    else
        export PATH="/Users/YerName/anaconda3/bin:$PATH"
    fi
fi
unset __conda_setup
# <<< conda initialize <<<


RPS1='$(basename $CONDA_PREFIX) - $(kubectx_prompt_info)'


#Yer Fortunes
if [ -x /opt/homebrew/bin/cowsay -a -x /opt/homebrew/bin/fortune -a -x /opt/homebrew/bin/lolcat ]; then
	cowlist=( $(cowsay -l | sed "1 d") );
	thechosencow=${cowlist[$(($RANDOM % ${#cowlist[*]}))]}
	fortune | cowsay -f "$thechosencow" | lolcat
fi

#THIS MUST BE AT THE END OF THE FILE FOR SDKMAN TO WORK!!!
[[ -s "$SDKMAN/sdkman-init.sh" ]] && source "$SDKMAN/sdkman-init.sh"

conda activate ml

IMPORTANT!:
DO NOT copy verbatim
these are meant as examples to learn from;
follow OhMyZsh documentation instead.

It is included here for convenience or as reference when going through setup checks or when installing the second time through.

Most useful plugins:

The Zsh Plugins we find most helpful are:

gh: GitHub CLI
git: Git CLI
kubectl: Kubernetes CLI
gradle: Gradle CLI

SDK

Our most important SDK manager is SDK Man. Install it as a local user install as documented on the SDK Man website: curl -s "https://get.sdkman.io" | bash

Install at least:

sdk install java
sdk install gradle
# optionally
sdk install kotlin

check with…

sdk current

Declare project dependencies:

See Env Commands!

#.sdkmanrc at project root

# Enable auto-env through the sdkman_auto_env config
# Add key=value pairs of SDKs to use below
java=21.0.4-tem
gradle=8.9
# optionally
kotlin=2.0.0

`asdf`

This tool also manages several different language ecosystems. It works by the concept of ‘plugins’ - see documentation here. We use it as a favorite tool to manage ruby versions and libraries.

NOTE: Having followed the site support guide, you have already encountered this sdk manager.

Installation and options:

There are many good ways to install asdf. We use brew as the least time-consuming approach.

brew install coreutils curl asdf

Install `ruby`

asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git
asdf plugin update --all
asdf install ruby 3.3.4
asdf global ruby 3.3.4
asdf list ruby  

More on `ruby` and Mac OS X

https://blog.macadmin.me/posts/asdf-on-macos/

Conda

… and Python 😜

IMPORTANT: Conda Install Options!

We use conda (community) and conda-forge tool

i.e. Miniforge!
https://github.com/conda-forge/miniforge

to manage our python ML environment and dependencies.

Miniforge Install

Download Miniforge fat Release, or

curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
bash Miniforge3-$(uname)-$(uname -m).sh

Follow all the excellent documentation on the conda website - there’s really little to add.

Preferred Alternative by Lugaru

Lugaru did this instead:

brew install miniforge

Annoyed by PS choice?

NOTE: When using custom left and right PS disable conda’s like so: conda config --set changeps1 false

What’s in `forge`?

https://conda.anaconda.org/conda-forge/

Volta

volta.sh, getting started guide.

curl https://get.volta.sh | bash

Follow the project’s documentation and references.

NOTE: Unlike other JS ecosystem management tools volta ALWAYS keeps track of call source folder!, thus offering global packages feel without the actual global risks.

Docker

Docker Desktop is still the easiest way to provision Docker and Kubernetes on Mac OS X and the primary way that we recommend containerizing locally.

Please note that Docker Company arrives with the new funding model to which we recommend having a personal-professional subscription.

Alternatively, the Abiosoft’s Colima is a viable alternative to Docker Desktop approach.

Jupyter

… and forks:

Having conda and containers Jupyter Notebooks, or Google Colab, are a straightforward installation option. This is also true for additional kernels like R, Kotlin, Scala, etc.

However, there is a better way - please see the IDE section next!

IDEs

We use the following IDEs:

JetBrains Toolbox App - managing all IDEs:
- Intellij IDEA Ultimate - core Java development;
- DataSpell - Python ML and AI development;
  - this supersedes Jupyter Notebook based tools;
  - this supersedes PyCharm Professional Edition;
  - NOTE: PyCharm Professional Edition and Jupyter Notebook are viable alternatives;
- WebStorm - JavaScript and TypeScript development;
VScode - a free alternative to professional tools.

Additional Considerations

There are a number of related considerations and crosscut concerns that need to be addressed and may require tools. For most of these we will rely on rdd13r and other senior members of our community once we come to. Topics that we already keep in mind are:

Design Quality and Validation: “how do we know that our way is the right one?”;
Code Quality and Validation: “how do we know that our code is the right one?”;
Documentation: “how do we know that our documentation is just right?”;
Code Maintenance: “how do we know that our code will endure?”;
Opportunity Match: “how do we know that our project will be successful?.”

Log

This is the initial draft of the guide - please see the CONTRIBUTING.md file for evolution.

Navigation by Anominous;
Driving by Lugaru;
Captured by rdd13r.
v0.1.

Echoes of the Wasteland Library Development

Captain Lugaru

Box Setup

Java Setup

Python Setup

Local Box Setup Overview

Ops!

Local Shell Setup

(Optional) Local Configuration Optimization

Most useful plugins:

SDK

Install at least:

Declare project dependencies:

`asdf`

Installation and options:

Install `ruby`

More on `ruby` and Mac OS X

Conda

Miniforge Install

Preferred Alternative by Lugaru

Annoyed by PS choice?

What’s in `forge`?

Volta

Docker

Jupyter

IDEs

Additional Considerations

Log

Echoes of the Wasteland Library Development

Captain Lugaru

Box Setup

Java Setup

Python Setup

Local Box Setup Overview

Ops!

Local Shell Setup

(Optional) Local Configuration Optimization

Most useful plugins:

SDK

Install at least:

Declare project dependencies:

asdf

Installation and options:

Install ruby

More on ruby and Mac OS X

Conda

Miniforge Install

Preferred Alternative by Lugaru

Annoyed by PS choice?

What’s in forge?

Volta

Docker

Jupyter

IDEs

Additional Considerations

Log

`asdf`

Install `ruby`

More on `ruby` and Mac OS X

What’s in `forge`?