Docs: updating getting started guide and simplifying via Scala 3.5.0

compiler/stages/src/main/scala/dfhdl/options/CompilerOptions.scala

@@ -6,6 +6,7 @@ import dfhdl.core.{ClkCfg, RstCfg}
 import java.io.File.separatorChar
 
 import CompilerOptions.*
+import dfhdl.internals.scastieIsRunning
 final case class CompilerOptions(
     commitFolder: CommitFolder,
     newFolderForTop: NewFolderForTop,
@@ -74,7 +75,7 @@ object CompilerOptions:
 
   opaque type PrintGenFiles <: Boolean = Boolean
   object PrintGenFiles:
-    given PrintGenFiles = false
+    given PrintGenFiles = if (scastieIsRunning) true else false
     given Conversion[Boolean, PrintGenFiles] = identity
 
   opaque type DropUserOpaques <: Boolean = Boolean

docs/getting-started/hello-world/index.md

@@ -5,7 +5,7 @@
 Since DFHDL is a Scala library, were are creating a Scala program that takes DFHDL designs and compiles (transpiles) them into lower representations (e.g., VHDL or Verilog). As such, some of DFHDL's compilation process is done statically via the Scala compiler and the rest during the Scala runtime execution. The Scala code below describes a program that runs the DFHDL compiler on an 8-bit overlapping counter design, `Counter8`. 
 
 ```{.scala .copy}
---8<-- "docs/getting-started/hello-world/scala-cli-project/Counter8.scala"
+--8<-- "docs/getting-started/hello-world/scala-project/Counter8.scala"
 ```
 
 !!! summary "Writing a DFHDL compilation program – as easy as 01-10-11!"
@@ -18,7 +18,7 @@ Since DFHDL is a Scala library, were are creating a Scala program that takes DFH
 
 ???dfhdl "Run it here"
     ```scastie
-    --8<-- "docs/getting-started/hello-world/scala-cli-project/Counter8.scala"
+    --8<-- "docs/getting-started/hello-world/scala-project/Counter8.scala"
     ```
 
 For more examples that are available to run in your browser, see the [relevant section][run-in-browser].
@@ -29,44 +29,44 @@ To run this example on your system, make sure to first follow the [initial setup
 
 You have several options to run Scala programs on your system:
 
-* For this simple `Counter8` example, you can just use the simplest [scala-cli-single-file][scala-cli-single-file] approach. 
-* For common DFHDL projects, we recommend using the [scala-cli project][scala-cli-project] approach. 
-* For more complex, full-production DFHDL projects, we recommended using an [sbt project][sbt-project].
+* For this simple `Counter8` example, you can just use the simplest [scala-single-file][scala-single-file] approach. 
+* For common DFHDL projects, we recommend using the [scala project][scala-project] approach. 
+* For complex, full-production DFHDL projects, you may need to use an [sbt project][sbt-project], but this is usually not required.
 
-### Scala-cli Single File
+### Scala Single File
 
-???dfhdl "View the scala-cli single file example"
+???dfhdl "View the scala single file example"
 
     ```{.scala .copy title="Counter8.scala"}
-    --8<-- "docs/getting-started/hello-world/scala-cli-single-file/Counter8.scala"
+    --8<-- "docs/getting-started/hello-world/scala-single-file/Counter8.scala"
     ```
 
 ```{.console .copy linenums="0" title="Download and run in your terminal"}
-curl -o Counter8.scala https://dfianthdl.github.io/getting-started/hello-world/scala-cli-single-file/Counter8.scala
-scala-cli run ./Counter8.scala
+curl -o Counter8.scala https://dfianthdl.github.io/getting-started/hello-world/scala-single-file/Counter8.scala
+scala run ./Counter8.scala
 ```
 
-For more information, please consult the [scala-cli documentation](https://scala-cli.virtuslab.org/docs/overview){target="_blank"}.
+For more information, please run `scala run --help` or consult the [online documentation](https://scala-cli.virtuslab.org/docs/commands/run){target="_blank"}.
 
-### Scala-cli Project
+### Scala Project
 
-???dfhdl "View the scala-cli project files example"
+???dfhdl "View the scala project files example"
 
     ```{.scala .copy title="projectFolder/project.scala"}
-    --8<-- "docs/getting-started/hello-world/scala-cli-project/project.scala"
+    --8<-- "docs/getting-started/hello-world/scala-project/project.scala"
     ```
 
     ```{.scala .copy title="projectFolder/Counter8.scala"}
-    --8<-- "docs/getting-started/hello-world/scala-cli-project/Counter8.scala"
+    --8<-- "docs/getting-started/hello-world/scala-project/Counter8.scala"
     ```
 
 ```{.console .copy linenums="0" title="Download and run in your terminal"}
-curl -o project.scala https://dfianthdl.github.io/getting-started/hello-world/scala-cli-project/project.scala
-curl -o Counter8.scala https://dfianthdl.github.io/getting-started/hello-world/scala-cli-project/Counter8.scala
-scala-cli run .
+curl -o project.scala https://dfianthdl.github.io/getting-started/hello-world/scala-project/project.scala
+curl -o Counter8.scala https://dfianthdl.github.io/getting-started/hello-world/scala-project/Counter8.scala
+scala run .
 ```
 
-For more information, please consult the [scala-cli documentation](https://scala-cli.virtuslab.org/docs/overview){target="_blank"}.
+For more information, please run `scala run --help` or consult the [online documentation](https://scala-cli.virtuslab.org/docs/commands/run){target="_blank"}.
 
 
 ### sbt Project
@@ -89,11 +89,11 @@ We recommend to actively use [Scalafmt](https://scalameta.org/scalafmt/){target=
 ???dfhdl "View the Scalafmt recommended configuration file"
 
     ```{.toml .copy title="projectFolder/.scalafmt.conf"}
-    --8<-- "docs/getting-started/hello-world/scala-cli-project/.scalafmt.conf"
+    --8<-- "docs/getting-started/hello-world/scala-project/.scalafmt.conf"
     ```
 
 ```{.console .copy linenums="0" title="Download it via your terminal"}
-curl -o .scalafmt.conf https://dfianthdl.github.io/getting-started/hello-world/scala-cli-project/.scalafmt.conf
+curl -o .scalafmt.conf https://dfianthdl.github.io/getting-started/hello-world/scala-project/.scalafmt.conf
 ```
 
 For more information, please consult the [Scalafmt documentation](https://scalameta.org/scalafmt/docs/configuration.html){target="_blank"}.

docs/getting-started/initial-setup/index.md

@@ -1,122 +1,174 @@
 # Initial Setup {#getting-started}
 
-DFHDL is a domain specific language (DSL) library written in the [Scala programming language](https://www.scala-lang.org){target="_blank"} (Scala 3.4), and as such it lets you utilize the entire Scala ecosystem, including IDEs, various tools, and other libraries. 
+DFHDL is a domain specific language (DSL) library written in the [Scala programming language](https://www.scala-lang.org){target="_blank"} (Scala 3.5), and as such it lets you utilize the entire Scala ecosystem, including IDEs, various tools, and other libraries. 
 
 Is your system already fit for Scala development? [Jump to the DFHDL hello-world section][hello-world]
 
 ## Installing Scala and Other Dependencies
 
-We recommend installing Scala via [Coursier](https://get-coursier.io/){target="_blank"}:
+We recommend directly installing Scala 3.5 (no need to install either [Coursier](https://get-coursier.io/){target="_blank"}, [Scala CLI](https://scala-cli.virtuslab.org/){target="_blank"}, or [sbt](https://www.scala-sbt.org/){target="_blank"}):
 
 <div class="grid cards" markdown>
 
 -   :fontawesome-brands-windows:{ .lg .middle } __Windows Instructions__
 
     ---
 
-    === "Manual"
+    === "Using [Chocolatey](https://community.chocolatey.org/)"
 
-        1. Download the [installer zip file](https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-win32.zip).
-
-        2. Open the zip.
-
-        3. Double click the `cs-x86_64-pc-win32.exe` executable to extract and run Coursier setup.
-
-    === "CMD"
-
-        Run the following in Windows command:
+        Run the following in Windows command or powershell:
 
         ```{.cmd .copy linenums="0"}
-        curl -fLo cs-x86_64-pc-win32.zip https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-win32.zip
-        tar -xf cs-x86_64-pc-win32.zip
-        move cs-x86_64-pc-win32.exe cs.exe
-        .\cs setup
-        ```
-
-    === "Powershell"
-
-        Run the following in Windows Powershell:
-
-        ```{.powershell .copy linenums="0"}
-        Invoke-WebRequest -Uri "https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-win32.zip" -OutFile "cs-x86_64-pc-win32.zip"
-        Expand-Archive -Path "cs-x86_64-pc-win32.zip"
-        Rename-Item -Path "cs-x86_64-pc-win32.exe" -NewName "cs.exe"
-        Remove-Item -Path "cs-x86_64-pc-win32.zip"
-        .\cs setup
+        choco install scala --version=3.5.0 
         ```
 
-
 -   :fontawesome-brands-linux:{ .lg .middle } __Linux Instructions__
 
     ---
 
-    === "x86-64 (aka AMD64)"
+    === "Using [SDKMAN!](https://sdkman.io/)"
 
         Run the following in your shell:
 
         ```{.sh-session .copy linenums="0"}
-        curl -fL "https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-linux.gz" | gzip -d > cs
-        chmod +x cs
-        ./cs setup
+        sdk install scala 3.5.0 
         ```
 
-    === "ARM64"
+-   :fontawesome-brands-apple:{ .lg .middle } __macOS Instructions__
+
+    ---
+
+    === "Using [Homebrew](https://brew.sh/)"
 
         Run the following in your shell:
 
         ```{.sh-session .copy linenums="0"}
-        curl -fL "https://github.com/VirtusLab/coursier-m1/releases/latest/download/cs-aarch64-pc-linux.gz" | gzip -d > cs
-        chmod +x cs
-        ./cs setup
+        brew update
+        brew install scala
         ```
 
-    === "Other linux"
+-   :material-help:{ .lg .middle } __Other OS/Instructions__
 
-        [:octicons-arrow-right-24: Goto Coursier's website](https://get-coursier.io/docs/cli-installation){target="_blank"}
+    ---
 
+    If for some reason the instructions above don't work for you, you can try to install Scala via [Coursier](https://get-coursier.io/){target="_blank"} using the information below.
 
--   :fontawesome-brands-apple:{ .lg .middle } __macOS Instructions__
+</div>
 
-    ---
 
-    === "via Brew"
+???info "Installing Scala via [Coursier](https://get-coursier.io/){target="_blank"}"
 
-        Run the following in your shell:
+    We recommend directly installing Scala, as instructed above. However, if you are experiencing issues, you can try installing Scala via Coursier, as follows:
 
-        ```{.sh-session .copy linenums="0"}
-        brew install coursier/formulas/coursier
-        cs setup
-        ```
+    <div class="grid cards" markdown>
 
-    === "aarch64 (M1,M2,...)"
+    -   :fontawesome-brands-windows:{ .lg .middle } __Windows Instructions__
 
-        Run the following in your shell:
+        ---
 
-        ```{.sh-session .copy linenums="0"}
-        curl -fL https://github.com/VirtusLab/coursier-m1/releases/latest/download/cs-aarch64-apple-darwin.gz | gzip -d > cs
-        chmod +x cs
-        ./cs setup
-        ```
+        === "Manual"
 
-    === "x86-64"
+            1. Download the [installer zip file](https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-win32.zip).
 
-        Run the following in your shell:
+            2. Open the zip.
 
-        ```{.sh-session .copy linenums="0"}
-        curl -fL https://github.com/coursier/launchers/raw/master/cs-x86_64-apple-darwin.gz | gzip -d > cs
-        chmod +x cs
-        ./cs setup
-        ```
+            3. Double click the `cs-x86_64-pc-win32.exe` executable to extract and run Coursier setup.
 
--   :material-help:{ .lg .middle } __Other OS/Instructions__
+        === "CMD"
 
-    ---
+            Run the following in Windows command:
 
-    For other OS or instructions please consult the Coursier website.
+            ```{.cmd .copy linenums="0"}
+            curl -fLo cs-x86_64-pc-win32.zip https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-win32.zip
+            tar -xf cs-x86_64-pc-win32.zip
+            move cs-x86_64-pc-win32.exe cs.exe
+            .\cs setup
+            ```
 
-    [:octicons-arrow-right-24: Goto Coursier's website](https://get-coursier.io/docs/cli-installation){target="_blank"}
+        === "Powershell"
 
-</div>
+            Run the following in Windows Powershell:
+
+            ```{.powershell .copy linenums="0"}
+            Invoke-WebRequest -Uri "https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-win32.zip" -OutFile "cs-x86_64-pc-win32.zip"
+            Expand-Archive -Path "cs-x86_64-pc-win32.zip"
+            Rename-Item -Path "cs-x86_64-pc-win32.exe" -NewName "cs.exe"
+            Remove-Item -Path "cs-x86_64-pc-win32.zip"
+            .\cs setup
+            ```
+
+
+    -   :fontawesome-brands-linux:{ .lg .middle } __Linux Instructions__
+
+        ---
+
+        === "x86-64 (aka AMD64)"
+
+            Run the following in your shell:
+
+            ```{.sh-session .copy linenums="0"}
+            curl -fL "https://github.com/coursier/launchers/raw/master/cs-x86_64-pc-linux.gz" | gzip -d > cs
+            chmod +x cs
+            ./cs setup
+            ```
+
+        === "ARM64"
+
+            Run the following in your shell:
+
+            ```{.sh-session .copy linenums="0"}
+            curl -fL "https://github.com/VirtusLab/coursier-m1/releases/latest/download/cs-aarch64-pc-linux.gz" | gzip -d > cs
+            chmod +x cs
+            ./cs setup
+            ```
+
+        === "Other linux"
+
+            [:octicons-arrow-right-24: Goto Coursier's website](https://get-coursier.io/docs/cli-installation){target="_blank"}
+
+
+    -   :fontawesome-brands-apple:{ .lg .middle } __macOS Instructions__
+
+        ---
+
+        === "via Brew"
+
+            Run the following in your shell:
+
+            ```{.sh-session .copy linenums="0"}
+            brew install coursier/formulas/coursier
+            cs setup
+            ```
+
+        === "aarch64 (M1,M2,...)"
+
+            Run the following in your shell:
+
+            ```{.sh-session .copy linenums="0"}
+            curl -fL https://github.com/VirtusLab/coursier-m1/releases/latest/download/cs-aarch64-apple-darwin.gz | gzip -d > cs
+            chmod +x cs
+            ./cs setup
+            ```
+
+        === "x86-64"
+
+            Run the following in your shell:
+
+            ```{.sh-session .copy linenums="0"}
+            curl -fL https://github.com/coursier/launchers/raw/master/cs-x86_64-apple-darwin.gz | gzip -d > cs
+            chmod +x cs
+            ./cs setup
+            ```
+
+    -   :material-help:{ .lg .middle } __Other OS/Instructions__
+
+        ---
+
+        For other OS or instructions please consult the Coursier website.
+
+        [:octicons-arrow-right-24: Goto Coursier's website](https://get-coursier.io/docs/cli-installation){target="_blank"}
+
+    </div>
 
 
 ## IDE Setup
@@ -127,7 +179,7 @@ Here is a summary of relevant IDEs:
 
 <div class="grid cards" markdown>
 
--   :simple-visualstudiocode:{ .lg .middle } __VS Code (Recommended)__
+-   :material-microsoft-visual-studio-code:{ .lg .middle } __VS Code (Recommended)__
 
     ---