squared 0.3.12 → 0.3.14

data/README.ruby.md

@@ -1,466 +0,0 @@
-# squared 0.3
-
-* [source](https://github.com/anpham6/squared)
-* [manifest](https://github.com/anpham6/squared-repo)
-* [docs](https://squared.readthedocs.io)
-
-## Version Compatibility
-
-| Date       | squared |    Min |    Max |    Git |
-| :--------: | ------: | -----: | -----: | -----: |
-| 2024-12-07 |   0.1.0 |  2.4.0 |  3.3.6 |   2.39 |
-| 2025-01-07 |   0.2.0 |  2.4.0 |  3.4.0 |   2.39 |
-| 2025-02-07 |   0.3.0 |  2.4.0 |  3.4.1 |   2.39 |
-
-The range chart indicates the latest Ruby tested against at the time of release.
-
-## Installation
-
-```sh
-gem install squared
-```
-
-### Optional
-
-* [Repo](https://source.android.com/docs/setup/reference/repo)
-* Python 3.6
-* Not compatible with Windows
-
-```sh
-mkdir -p ~/.bin
-PATH="${HOME}/.bin:${PATH}"
-curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo
-chmod a+rx ~/.bin/repo
-```
-
-## Example - Rakefile
-
-Projects from any accessible folder can be added relative to the parent directory (e.g. *REPO_ROOT*) or absolutely. The same Rakefile can also manage other similarly cloned `Repo` repositories remotely by setting the `REPO_ROOT` environment variable to the location. Missing projects will simply be excluded from the task runner.
-
-```ruby
-require "squared"
-
-require "squared/workspace"
-require "squared/workspace/repo"                     # Optional
-require "squared/workspace/project/node"             #
-require "squared/workspace/project/python"           #
-require "squared/workspace/project/ruby"             #
-# OR
-require "squared/app"                                # All workspace related modules
-
-# NODE_ENV  = production
-
-# REPO_ROOT = /workspaces                            #
-# REPO_HOME = /workspaces/squared                    # Dir.pwd
-# rake      = /workspaces/squared/Rakefile           # main?
-# OR
-# REPO_ROOT = /workspaces                            # Dir.pwd
-# rake      = /workspaces/Rakefile                   #
-# REPO_HOME = /workspaces/squared                    # main: "squared"
-
-# pathname  = /workspaces/pathname
-# optparse  = /workspaces/optparse
-# log       = /workspaces/logger
-# emc       = /workspaces/e-mc
-# pir       = /workspaces/pi-r
-# squared   = /workspaces/squared
-# cli       = /workspaces/squared/publish/sqd-cli
-# sqd-serve = /workspaces/squared/publish/sqd-serve
-# sqd       = /workspaces/squared/sqd
-
-Workspace::Application
-  .new(Dir.pwd, main: "squared") # Dir.pwd? (main? is implicitly basename)
-  .banner("group", "project", styles: ["yellow", "black"], border: "bold") # name | project | path | ref | group? | parent? | version?
-  .repo("https://github.com/anpham6/squared-repo", "nightly", script: ["build:dev", "build:prod"], ref: :node) # Repo (optional)
-  .run("rake install", ref: :ruby)
-  .depend(false, group: "default")
-  .clean("rake clean", group: "default")
-  .clean(["build/"], group: "app")
-  .log({ file: "tmp/%Y-%m-%d.log", level: "debug" }, group: "app")
-  .add("pathname", run: "rake compile", copy: "rake install", test: "rake test", group: "default", env: { # Ruby (with C extensions)
-    "CFLAGS" => "-fPIC -O1"
-  })
-  .add("optparse", doc: "rake rdoc", group: "default") # Uses bundler/gem_tasks (without C extensions)
-  .add("logger", copy: { from: "lib", glob: "**/*.rb", into: "~/.rvm/gems/ruby-3.4.0/gems/logger-1.6.1" }, clean: ["tmp/"]) # autodetect: true
-  .add("e-mc", "emc", copy: { from: "publish", scope: "@e-mc", also: [:pir, "squared-express/"] }, ref: :node) # Node
-  .add("pi-r", "pir", copy: { from: "publish", scope: "@pi-r" }, clean: ["publish/**/*.js", "tmp/"]) # Trailing slash required for directories
-  .add("squared", script: ["build:stage1", "build:stage2"], group: "app") do # Copy target (main)
-    # Repo (global)
-    as(:run, "build:dev", "dev")                           # npm run build:dev -> npm run dev
-    as(:run, { "build:dev": "dev", "build:prod": "prod" })
-
-    add("publish/sqd-cli", "cli", exclude: [:git]) # rake cli:build
-    add("publish/sqd-serve")                       # rake sqd-serve:build
-    add("publish/sqd-admin", group: "sqd", exclude: [:base])
-    # OR
-    with(exclude: [:base]) { add("publish/*", "packages") } # rake packages:sqd-serve:build
-    # OR
-    add(["publish/sqd-cli", "publish/sqd-serve", "publish/sqd-admin"], true, exclude: [:base]) # rake squared:sqd-serve:build
-  end
-  .add("squared/sqd", exclude: :git, pass: [:node, 'checkout', 'bump']) do # Skip initialize(:node) + squared:checkout:* + squared:bump:*
-    variable_set :script, "build:sqd"   # Override detection
-    variable_set :depend, false
-    variable_set :clean, ["build/sqd/"]
-  end
-  .pass("pull", group: "default") { test? || doc? } # pathname:pull | optparse:pull
-  .style("banner", 255.255) # 256 colors (fg | fg.bg | -0.bg)
-  .build(default: "build", parallel: ["pull", "fetch", "rebase", "copy", "clean", /^outdated:/], pass: ['publish']) do |workspace|
-    workspace
-      .enable_aixterm
-      .style({
-        banner: ["bright_cyan", "bold", "bright_black!"],
-        border: "bright_white"
-      })
-  end
-
-# default   = /workspaces/ruby/*
-# pathname  = /workspaces/ruby/pathname
-# optparse  = /workspaces/ruby/optparse
-# logger    = /workspaces/ruby/logger
-# android   = /workspaces/android-docs
-# chrome    = /workspaces/chrome-docs
-
-Workspace::Application
-  .new(ENV["SQUARED_HOME"], prefix: "rb", common: false)        # Local styles
-  .group("ruby", "default", run: "rake build", copy: "rake install", clean: "rake clean", ref: :ruby, override: {
-    pathname: {
-      run: "rake compile"                                       # rake rb:pathname:build
-    }
-  })
-  .with(:python) do                                             # ref=Symbol | group=String
-    banner([:name, ": ", :version], "path")                     # chrome-docs: 0.1.0 | /workspaces/chrome-docs
-    doc("make html")                                            # rake rb:doc:python
-    run(false)                                                  # rake rb:build:python (disabled)
-    exclude(%i[base git])                                       # Project::Git.ref (superclass)
-    add("android-docs", "android")                              # rake rb:android:doc
-    add("chrome-docs", "chrome")                                # rake rb:chrome:doc
-  end
-  .style("inline", "bold")
-  .build
-```
-
-**NOTE**: The use of "**ref**" (class name) is only necessary when initializing an empty directory (e.g. *rake repo:init*).
-
-### Clone
-
-The task is only active when the project directory is empty or does not exist.
-
-```ruby
-Workspace::Application
-  .new(main: "squared")
-  .git(
-    "emc": "https://github.com/anpham6/e-mc",                   # rake emc:clone
-    "pir": {                                                    # rake pir:clone
-      uri: "https://github.com/anpham6/pi-r",                   #
-      options: {                                                #
-        "origin": "github",                                     # --origin='github'
-        "recurse-submodules": false,                            # --no-recurse-submodules
-        "shallow-exclude": ["v0.0.1", "v0.0.2"]                 # --shallow-exclude='v0.0.1' --shallow-exclude='v0.0.2'
-      }
-    }
-  )
-  .git("squared", "/path/to/squared", options: { local: true }) # Relative paths resolve from workspace root
-  .git(
-    {
-      emc: { uri: "e-mc", options: { "depth": 2 } },            # https://github.com/anpham6/e-mc
-      pir: "pi-r"                                               # Maps task alias to repository folder
-    },
-    base: "https://github.com/anpham6",                         # Required
-    repo: ["squared", "android-docs", "chrome-docs"],           # https://github.com/anpham6/squared
-    options: {                                                  # Only "repo"
-      "depth": 1,
-      "quiet": true
-    }
-  )
-  .with(:node) do                                               # rake clone:node
-    add("e-mc", "emc")                                          # https://github.com/anpham6/e-mc
-    add("pi-r", "pir")                                          # https://github.com/anpham6/pi-r
-    add("squared")                                              # https://github.com/anpham6/squared
-  end
-  .with(:python) do                                             # rake clone:python
-    add("android-docs")
-    add("chrome-docs")
-  end
-  .git("https://github.com/anpham6")                            # Uses already defined root projects
-  .git("https://github.com/anpham6", ["emc", "pir"])            # Targets any defined project
-  .build(parallel: ["clone"])                                   # rake clone + rake clone:sync
-```
-
-### Graph
-
-```ruby
-Workspace::Application
-  .new(main: "squared")
-  .graph(["depend"], ref: :git) # Optional
-  .with(:python) do
-    add("android-docs", "android")
-    add("chrome-docs", "chrome", graph: "android")
-  end
-  .with(:node) do
-    graph(["build", "copy"], on: {                                               # Overrides "git"
-      first: proc { puts "1" },
-      last: proc { puts "2" }
-    })
-    script("build:dev")                                                          # npm run build:dev
-    # OR
-    run([nil, "build:dev", { "PATH" => "~/.bin" }, "--workspace", "--silent"])   # PATH="~/.bin" npm run build:dev --workspace -- --silent
-
-    add("e-mc", "emc") do
-      first("build", "emc:clean", "emc:depend")                                  # rake emc:clean && rake emc:depend && rake emc:build && echo "123"
-      last("build", out: "123") { |out: nil| puts out }                          #
-      error("build") { |err: nil| log.debug err }                                #
-    end
-    add("pi-r", "pir", graph: "emc", first: {
-      build: proc { puts self.name }                                             # puts "pir"
-    })
-    add("squared-express", "express", graph: "pir")
-    add("squared", graph: ["chrome", "express"]) do
-      first("git:ls-files") { puts path }
-      last("git:ls-files") { puts workspace.root }
-    end
-  end
-  .with(:ruby) do
-    run("gem build")                                                             # gem build
-    # OR
-    run(["gem build", "--force", { "RUBY_VERSION" => "3.4.0" }])                 # RUBY_VERSION="3.4.0" gem build --force
-    # OR
-    run(["gem pristine", ["gem build", "gem cleanup"], nil, "--debug"])          # gem pristine --debug && gem build --debug && gem cleanup --debug
-    # OR
-    run([                                                                        # PATH="~/.bin" GEM_HOME="~/.gems/ruby-3.4.0" (merged)
-      ["gem pristine", "--all", { "PATH" => "~/.bin" }, "--silent"],             # gem pristine --silent --all
-      ["gem build", { strict: true }, { "GEM_HOME" => "~/.gems/ruby-3.4.0" }]    # gem build --strict
-    ])
-
-    add("pathname", test: ["rake test", { jobs: ENV["RAKE_JOBS"] }])             # rake test --jobs 4
-    add("fileutils", graph: "pathname")
-    add("optparse", run: "gem build", env: { "PATH" => "~/.bin" }, opts: "-v")   # PATH="~/.bin" gem build -v
-    add("rake", graph: ["fileutils", "optparse"])
-    banner(command: false)                                                       # Always hide banner
-  end
-  .build
-```
-
-```sh
-rake pir:graph      # emc + pir
-rake express:graph  # emc + pir + express
-rake chrome:graph   # android + chrome
-rake graph:python   # same
-rake squared:graph  # android + chrome + emc + pir + express + squared
-rake graph:node     # same
-rake rake:graph     # pathname + fileutils + optparse + rake
-rake graph:ruby     # same
-rake graph          # graph:node + graph:ruby
-
-rake squared:graph:run[express,pir]  # emc + pir + express + squared
-rake squared:graph:run[node,-emc]    # pir + express + squared
-```
-
-### Batch
-
-```ruby
-Workspace::Series.batch(:ruby, :node, {
-  stage: %i[graph test],
-  reset: %i[stash pull]
-})
-```
-
-### Rename
-
-```ruby
-Workspace::Series.rename("depend", "install")
-```
-
-## Usage
-
-```sh
-rake -T               # List tasks
-rake                  # rake status (usually "build")
-
-# GIT_OPTIONS=rebase
-rake pull             # All except "default" + "app"
-rake pull:ruby        # pathname + optparse + logger
-rake pull:default     # pathname + optparse
-rake pull:app         # squared
-rake pull:node        # emc + pir + squared
-
-rake build            # All except "android"
-rake doc              # optparse + android
-rake depend           # All except "default"
-
-rake build:ruby       # rake compile + rake install + rake install
-
-rake clean            # All except "default" + "app"
-rake clean:ruby       # rake clean + rake clean + ["tmp/"]
-rake clean:default    # rake clean + rake clean + skip
-rake clean:app        # none + skip + ["build/"]
-rake clean:node       # none + ["publish/**/*.js", "tmp/"] + ["build/"]
-
-rake squared:run[#]   # List scripts (node)
-rake squared:rake[#]  # List tasks (ruby)
-```
-
-```sh
-rake build:app                   # squared + cli + sqd-serve
-rake squared:build:workspace     # cli + sqd-serve
-rake pull:sqd                    # sqd-admin
-rake squared:pull:workspace      # sqd-serve + sqd-admin
-rake squared:outdated:workspace  # cli + sqd-serve + sqd-admin
-```
-
-## Methods
-
-Task:
-
-* run
-* script
-* depend
-* graph
-* doc
-* lint
-* test
-* clean
-
-Non-task:
-
-* log
-* exclude
-
-## Styles
-
-* banner
-* border
-* header
-* active
-* inline
-* current
-* major
-* red
-* yellow
-* green
-
-## Environment
-
-### Path
-
-All project executable programs can have their binary path set to a non-global alias.
-
-```ruby
-Common::PATH.merge!({
-  GIT: '/usr/bin/git',
-  GEM: '~/.rvm/rubies/ruby-3.4.0/bin/gem',
-  BUNDLE: '~/.rvm/gems/ruby-3.4.0/bin/bundle',
-  RAKE: '~/.rvm/gems/ruby-3.4.0/bin/rake',
-  NPM: '/opt/node/v22.0.0/bin/npm',
-  PYTHON: "#{ENV['PYTHONPATH']}/bin/python"
-})
-```
-
-### Build
-
-```ruby
-Workspace::Application
-  .new
-  .add("squared", run: "gcc a.c -o a.o", opts: { __debug__: { g: true, O2: true, c: nil }, c: true, j: 4 }) # gcc a.c -o a.o -c -j4
-
-BUILD_TYPE          # global
-
-# :env                                         :run           :opts :type
-# LD_LIBRARY_PATH="path/to/lib" CFLAGS="-Wall" gcc a.c -o a.o -g    -O2
-BUILD_${NAME}       # gcc a.c -o a.o
-BUILD_${NAME}_OPTS  # -g
-BUILD_${NAME}_ENV   # {"LD_LIBRARY_PATH":"path/to/lib","CFLAGS":"-Wall"} (hash/json)
-BUILD_${NAME}_TYPE  # debug
-
-# :env                                       :opts                               :script      :args
-# NODE_ENV="production" NO_COLOR="1" npm run --loglevel=error --workspaces=false build:dev -- --quiet
-BUILD_${NAME}       # build:dev
-BUILD_${NAME}_OPTS  # --loglevel=error --workspaces=false
-BUILD_${NAME}_ENV   # {"NODE_ENV":"production","NO_COLOR":"1"} (hash/json)
-BUILD_${NAME}_DEV   # pattern,0,1 (:dev)
-BUILD_${NAME}_PROD  # pattern,0,1 (:prod)
-SCRIPT_${NAME}_OPTS # --quiet
-
-BUILD_${NAME}=0     # skip project
-```
-
-### Graph
-
-```ruby
-GRAPH_${NAME}       # depend,build => squared:depend + squared:build
-GRAPH_${NAME}_PASS  # -emc,pir,express => pir + express
-```
-
-### Logger
-
-These global options also can target the project suffix `${NAME}`. (e.g. LOG_FILE_EMC)
-
-```ruby
-LOG_FILE            # %Y-%m-%d.log
-# OR
-LOG_AUTO            # year,y,month,m,day,d,1
-# Optional
-LOG_DIR             # exist?
-LOG_LEVEL           # See gem "logger"
-LOG_COLUMNS         # terminal width (default: 80)
-```
-
-### Repo
-
-These global options also can target the application main suffix `${NAME}`. (e.g. REPO_ROOT_SQUARED)
-
-```ruby
-REPO_ROOT           # parent dir
-REPO_HOME           # project dir (main)
-REPO_BUILD          # run,script
-REPO_GROUP          # string
-REPO_REF            # e.g. ruby,node
-REPO_DEV            # pattern,0,1
-REPO_PROD           # pattern,0,1
-REPO_WARN           # 0,1
-REPO_SYNC           # 0,1
-REPO_MANIFEST       # e.g. latest,nightly,prod
-REPO_TIMEOUT        # confirm dialog (seconds)
-```
-
-## Git
-
-Most project classes will inherit from `Git` which enables these tasks:
-
-| Task       | Git              |  Command                                      |
-| :--------- | :--------------- | :-------------------------------------------- |
-| branch     | branch           | create set delete move copy list edit current |
-| checkout   | checkout         | commit branch track detach path               |
-| commit     | commit           | add all amend amend-orig                      |
-| diff       | diff             | head cached branch files between contain      |
-| fetch      | fetch            | origin remote                                 |
-| files      | ls-files         | cached modified deleted others                |
-| pull       | pull             | origin remote                                 |
-| rebase     | rebase           | branch onto send                              |
-| refs       | ls-remote --refs | heads tags remote                             |
-| reset      | reset            | commit index patch mode                       |
-| restore    | restore          | source worktree staged overlay                |
-| rev        | rev              | commit branch output parseopt                 |
-| show       | show             | format oneline                                |
-| stash      | stash            | push pop apply drop list                      |
-| tag        | tag              | add delete list                               |
-
-You can disable all of them at once using the `exclude` property.
-
-```ruby
-Workspace::Application
-  .new
-  .add("squared", exclude: :git)
-```
-
-You can disable one or more of them using the `pass` property as a *string*.
-
-```ruby
-Workspace::Application
-  .new
-  .add("squared", pass: ["pull"], ref: :node)
-  .pass("pull", ref: :node) { read_packagemanager(:private) }
-```
-
-## LICENSE
-
-BSD 3-Clause