From 738be6f5c03aa03f8004e0e3f79860dfa8e9f5de Mon Sep 17 00:00:00 2001 From: James Ward Date: Wed, 31 Jul 2024 10:12:19 -0600 Subject: [PATCH] setup site --- .github/workflows/release.pkl | 64 ++++++++ .github/workflows/release.yml | 30 ++++ .gitignore | 2 + CNAME | 1 + README.md | 5 +- docs/about/authors.md | 7 + docs/about/license.md | 123 +++++++++++++++ docs/guide/CoursierDetailsUnused.txt | 96 ++++++++++++ docs/guide/examples.md | 60 ++++++++ docs/guide/scalatools.md | 216 +++++++++++++++++++++++++++ docs/index.md | 13 ++ mkdocs.yml | 24 +++ requirements.txt | 1 + 13 files changed, 638 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/release.pkl create mode 100644 .github/workflows/release.yml create mode 100644 .gitignore create mode 100644 CNAME create mode 100644 docs/about/authors.md create mode 100644 docs/about/license.md create mode 100644 docs/guide/CoursierDetailsUnused.txt create mode 100644 docs/guide/examples.md create mode 100644 docs/guide/scalatools.md create mode 100644 docs/index.md create mode 100644 mkdocs.yml create mode 100644 requirements.txt diff --git a/.github/workflows/release.pkl b/.github/workflows/release.pkl new file mode 100644 index 00000000..467004eb --- /dev/null +++ b/.github/workflows/release.pkl @@ -0,0 +1,64 @@ +// pkl eval --format yaml -o release.yml release.pkl + +amends "package://pkg.pkl-lang.org/github.com/jamesward/pklgha/pklgha@0.0.14#/GitHubAction.pkl" + +on { + push { + + } + workflow_dispatch { + + } +} + +permissions { + contents = "read" + pages = "write" + `id-token` = "write" +} + +concurrency { + group = "pages" + `cancel-in-progress` = false +} + +jobs { + ["deploy"] = new { + environment { + name = "github-pages" + url = "${{ steps.deployment.outputs.page_url }}" + } + `runs-on` = "ubuntu-latest" + + steps { + new { + uses = "actions/checkout@v4" + } + + new { + name = "generate website" + run = """ + pip install -r requirements.txt + + mkdocs build + """ + } + + new { + uses = "actions/configure-pages@v5" + } + + new { + uses = "actions/upload-pages-artifact@v3" + with { + ["path"] = "site" + } + } + + new { + id = "deployment" + uses = "actions/deploy-pages@v4" + } + } + } +} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 00000000..ea5eef96 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,30 @@ +# Generated file. DO NOT EDIT. +'on': + push: {} + workflow_dispatch: {} +permissions: + contents: read + pages: write + id-token: write +concurrency: + group: pages + cancel-in-progress: false +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: generate website + run: |- + pip install -r requirements.txt + + mkdocs build + - uses: actions/configure-pages@v5 + - uses: actions/upload-pages-artifact@v3 + with: + path: site + - id: deployment + uses: actions/deploy-pages@v4 + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..c4b5d81a --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +/.idea/ +/site/ diff --git a/CNAME b/CNAME new file mode 100644 index 00000000..f9521e3d --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +EffectOrientedProgramming.com diff --git a/README.md b/README.md index 8c15cd23..7662890b 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,2 @@ -# Effect Oriented Programming +# Effect Oriented Programming - Website -The book is coming soon! - -[Get notified when it is available](https://leanpub.com/effect-oriented-programming) diff --git a/docs/about/authors.md b/docs/about/authors.md new file mode 100644 index 00000000..e2fd3a33 --- /dev/null +++ b/docs/about/authors.md @@ -0,0 +1,7 @@ +# Authors + +## Bill Frasure + +## James Ward + +## Bruce Eckel diff --git a/docs/about/license.md b/docs/about/license.md new file mode 100644 index 00000000..0309b6b0 --- /dev/null +++ b/docs/about/license.md @@ -0,0 +1,123 @@ +# License + +All rights reserved. Printed in the United States of America. This publication +is protected by copyright, and permission must be obtained from the publisher +prior to any prohibited reproduction, storage in a retrieval system, or +transmission in any form or by any means, electronic, mechanical, photocopying, +recording, or likewise. For information regarding permissions, see +[EffectOrientedProgramming.com](https://www.effectorientedprogramming.com/). + +Created in Crested Butte, Colorado, USA. + +Text printed in the United States + +> **Ebook: Version 1.0, Month Year** +> +> **First printing Month Year** + +Cover design by Daniel Will-Harris, +[www.Will-Harris.com](http://www.Will-Harris.com) + +Many of the designations used by manufacturers and sellers to distinguish their +products are claimed as trademarks. Where those designations appear in this +book, and the publisher was aware of a trademark claim, the designations are +printed with initial capital letters or in all capitals. + +The Scala language is copyright: + +© 2002-2024 EPFL + +© 2011-2024 Lightbend, Inc. + +Java is a trademark or registered trademark of Oracle, Inc. in the United States and +other countries. Windows is a registered trademark of Microsoft Corporation in +the United States and other countries. All other product names and company +names mentioned herein are the property of their respective owners. + +The authors and publisher have taken care in the preparation of this book, but +make no expressed or implied warranty of any kind and assume no responsibility +for errors or omissions. No liability is assumed for incidental or +consequential damages in connection with or arising out of the use of the +information or programs contained herein. + +Visit us at [EffectOrientedProgramming.com](https://www.effectorientedprogramming.com/). + +## Source Code + +All the source code for this book is available as copyrighted freeware, +distributed via [GitHub](https://github.com/EffectOrientedProgramming/examples). +To ensure you have the most current version, this is the official code +distribution site. You may use this code in classroom and other educational +situations as long as you cite this book as the source. + +The primary goal of this copyright is to ensure that the source of the code is +properly cited, and to prevent you from republishing the code without +permission. (As long as this book is cited, using examples from the book in +most media is generally not a problem.) + +In each source-code file you find a reference to the following copyright notice: + +```text +// Copyright.txt +This computer source code is Copyright ©2024 Billding Software LLC. +All Rights Reserved. + +Permission to use, copy, modify, and distribute this +computer source code (Source Code) and its documentation +without fee and without a written agreement for the +purposes set forth below is hereby granted, provided that +the above copyright notice, this paragraph and the +following five numbered paragraphs appear in all copies. + +1. Permission is granted to compile the Source Code and to +include the compiled code, in executable format only, in +personal and commercial software programs. + +2. Permission is granted to use the Source Code without +modification in classroom situations, including in +presentation materials, provided that the book "Effect Oriented +Programming" is cited as the origin. + +3. Permission to incorporate the Source Code into printed +media may be obtained by contacting: + +Billding Software LLC, 111 Alpine Court, Crested Butte, CO 81224 +bill@billdingsoftware.com + +4. The Source Code and documentation are copyrighted by +Billding Software LLC. The Source code is provided without express +or implied warranty of any kind, including any implied +warranty of merchantability, fitness for a particular +purpose or non-infringement. Billding Software LLC does not +warrant that the operation of any program that includes the +Source Code will be uninterrupted or error-free. Billding Software +makes no representation about the suitability of the +Source Code or of any software that includes the Source +Code for any purpose. The entire risk as to the quality +and performance of any program that includes the Source +Code is with the user of the Source Code. The user +understands that the Source Code was developed for research +and instructional purposes and is advised not to rely +exclusively for any reason on the Source Code or any +program that includes the Source Code. Should the Source +Code or any resulting software prove defective, the user +assumes the cost of all necessary servicing, repair, or +correction. + +5. IN NO EVENT SHALL BILLDING SOFTWARE LLC, OR ITS PUBLISHER BE +LIABLE TO ANY PARTY UNDER ANY LEGAL THEORY FOR DIRECT, +INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, +INCLUDING LOST PROFITS, BUSINESS INTERRUPTION, LOSS OF +BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS, OR FOR +PERSONAL INJURIES, ARISING OUT OF THE USE OF THIS SOURCE +CODE AND ITS DOCUMENTATION, OR ARISING OUT OF THE INABILITY +TO USE ANY RESULTING PROGRAM, EVEN IF BILLDING SOFTWARE LLC, OR +ITS PUBLISHER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGE. BILLDING SOFTWARE LLC SPECIFICALLY DISCLAIMS ANY +WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE SOURCE CODE AND DOCUMENTATION PROVIDED +HEREUNDER IS ON AN "AS IS" BASIS, WITHOUT ANY ACCOMPANYING +SERVICES FROM BILLDING SOFTWARE LLC, AND BILLDING SOFTWARE LLC HAS NO +OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, +ENHANCEMENTS, OR MODIFICATIONS. diff --git a/docs/guide/CoursierDetailsUnused.txt b/docs/guide/CoursierDetailsUnused.txt new file mode 100644 index 00000000..a1913587 --- /dev/null +++ b/docs/guide/CoursierDetailsUnused.txt @@ -0,0 +1,96 @@ + + + + + + + + + diff --git a/docs/guide/examples.md b/docs/guide/examples.md new file mode 100644 index 00000000..a384b018 --- /dev/null +++ b/docs/guide/examples.md @@ -0,0 +1,60 @@ +# Running the Book Code + +## Install the Example Code + +Download the [zipped code repository](https://github.com/EffectOrientedProgramming/examples). +To find the zipped version, press the green "Code" button. +Unpack the archive. + +## Install IntelliJ IDEA + +We use IntelliJ IDEA to develop the examples in this book. +You may use another environment such as VSCode but if you do you'll need to figure it out yourself. + +1. Follow the instructions [here](https://www.jetbrains.com/help/idea/installation-guide.html) + to install IntelliJ IDEA. + +1. Start IntelliJ IDEA, and choose 'Open' to open an existing project. + Navigate to where you unzipped the repository. + +1. If the Scala plugin isn't installed, IDEA will prompt you. + Accept the prompt to install the plugin. + +1. When you open any of the chapter files in `src/main/scala`, as you scroll down you will + see green arrows on the left of each runnable example. + When you press an arrow, that example will run in a console and show you the output. + +1. You might need to restart JetBrains IDEA after configuring. + Also check for running tasks in the IDE; you might need to wait the first time you open the project before the green arrows appear. + + + +## Configuring the Scala SDK + +When you open a Scala file in IntelliJ, you might get a message in the title bar of that file: +``` +No Scala SDK in module +``` +On the right side of that message bar, you'll see: +``` +Setup Scala SDK +``` +Click on this. In the resulting dialog box, select "Create" and choose the latest Coursier version of Scala, which will be +version 3.x. The Dialog box will now look something like this: + +![image](https://user-images.githubusercontent.com/1001900/126879631-6490636e-7db5-4e4f-90c6-82292ff2569f.png) + +Select "OK". Now go to `File | Project Structure | Global Libraries` and Choose Scala 3, like this: + +![image](https://user-images.githubusercontent.com/1001900/126879808-1285e65e-e674-4a9b-9246-c86f86956e90.png) diff --git a/docs/guide/scalatools.md b/docs/guide/scalatools.md new file mode 100644 index 00000000..ca1d210b --- /dev/null +++ b/docs/guide/scalatools.md @@ -0,0 +1,216 @@ +# Installing Scala & Tools + +This is an overview of the setup process to install the tools necessary to run the examples from the book. +The following sections provide detailed instructions. + +1. Download and install [Coursier](https://get-coursier.io/). + [Coursier](https://get-coursier.io/docs/cli-overview) is the Scala installer we use to ensure that the right JVM and standard Scala tools are installed on your system. + Details are [here](https://docs.scala-lang.org/scala3/getting-started.html). + **Windows:** [Do This Instead](#6-windows-installation). +1. Run `cs setup --jvm 21`. This installs the Java Development Kit (JDK) version 21, Scala 3, and support tools such as the Scala Build Tool ([SBT](https://www.scala-sbt.org/)). + **Windows:** Just run `cs setup`. +1. Install an Integrated Development Environment (IDE): either [IntelliJ IDEA](https://www.jetbrains.com/help/idea/installation-guide.html) or Visual Studio Code (VSCode). +1. Download or clone the [examples repository](examples.md). +1. Open the repository in your IDE. +1. Install the Scala add-on for your IDE. + +## Notes + +1. We assume you know how to use the Command-Line Interface (CLI) a.k.a *shell* for your Operating System (OS: Windows, Macintosh or Linux). +If you do not, you can find instructions [here](https://github.com/BruceEckel/AtomicKotlinExamples/blob/master/README.md#appendix-a-command-line-basics). +These instructions were written for [Atomic Kotlin](https://www.atomickotlin.com/), so Kotlin will be referenced. + +2. If any terminology or processes described here are still not clear, you can usually find explanations or answers through +[Google](https://www.google.com/). For more specific issues or problems, try [StackOverflow](http://stackoverflow.com/). +Sometimes you can find installation instructions on [YouTube](https://www.youtube.com/). + +3. If after any installation step something doesn't seem to work, try closing your shell and opening a new one. + +## 1. Install Coursier + +**Windows Users:** [Go Here First](#6-windows-installation) + +The process for installing Coursier is different for each operating system. +The [Coursier Installation Instructions](https://get-coursier.io/docs/cli-installation) provide a detailed guide for each system. + + +## 2. Use Coursier to Install the Required Tools + +This command installs the JDK version 21, Scala 3, the SBT build tool, and several other tools. +We specify version 21 of Java on the `cs` command line: + +``` +cs setup --jvm 21 +``` + +**Windows:** Just run `cs setup` and it will find the JDK you installed [here](#6-windows-installation). + +This may take a few minutes. When prompted with a `[Y/n]` query, enter `y` for all options. + +## 3. Test Your Installation + +Once installation is complete, close the current shell and open a new one. +You can run a few quick tests to ensure the installation is successful: + +1\. `cs java -version` + Output will be something like: +```text +openjdk version "21.0.3" 2024-04-16 LTS +OpenJDK Runtime Environment Temurin-21.0.3+9 (build 21.0.3+9-LTS) +OpenJDK 64-Bit Server VM Temurin-21.0.3+9 (build 21.0.3+9-LTS, mixed mode, sharing) +``` + +If your Java version is not 21, update it with: + +```text +cs java --jvm 21 --setup +``` + +2\. `scalac -version` + Output will be something like: +```text +Scala compiler version 3.4.2 -- Copyright 2002-2024, LAMP/EPFL +``` + +3\. `sbt help` + Output will be something like: +```text +[info] welcome to sbt 1.10.0 (Eclipse Adoptium Java 21.0.3) +... +``` + +## 4. Using SBT + +In a terminal, move to the directory where you extracted the [examples](examples.md) repository and run: + +``` +sbt +``` + +This opens the sbt shell. For this project, the prompt will look something like this: + +``` +sbt:EffectOrientedProgramming> +``` + +There are numerous commands available in the sbt command shell. +To see them, type `help` at the sbt prompt. + +### Compiling + +To compile all the files in the current project, run `compile` in the sbt shell: + +``` +sbt:EffectOrientedProgramming> compile +``` + +You might see some warnings the first time you run `compile` after installing the repository but you can ignore them. + +### Running a Program + +`run` displays a list of all executables in the project: + +``` +sbt:EffectOrientedProgramming> run +``` + +To run a specific program, use `runMain`: + +``` +sbt:EffectOrientedProgramming> runMain programName +``` + +For example, to run `App0` from `Chapter03_Superpowers`: + +``` +sbt:EffectOrientedProgramming> run +(sbt displays numbered list of main programs) +Enter number: 1 +``` + +or + +``` +sbt:EffectOrientedProgramming> runMain Chapter03_Superpowers.App0 +``` + +> **NOTE: Some output might be out-of-order vs. output shown in the book**. +> Nodes in the same layer of the dependency graph have arbitrary ordering. +> The ordering of initialization in the dependency graph is only guaranteed in the sense that 'If B depends on A, then A will be constructed first.' +> But whenever there are unrelated pieces, the ordering is arbitrary. +> C could be constructed at any point: +> - Before A +> - In between A and B +> - After B +> As long as C doesn't depend on A or B. + + + +### Automatic Command Execution + +If you precede any command with `~`, sbt automatically runs that command whenever there is a change to the associated files. +For example: + +``` +sbt:EffectOrientedProgramming> ~runMain Chapter03_Superpowers.App0 +``` + +automatically runs `Chapter03_Superpowers.App0` whenever any of that program's files change. +Pressing the `ENTER` key stops the automated command. + +### Exiting + +To exit the sbt shell, press **ctrl + d**. + +## 5. Troubleshooting + +* Downloads can take a long time and might appear to be frozen. Just wait it out. + +* If Java is already installed, you might be missing the JDK or using the wrong version of Java. + Execute this command to fix the problem: + `cs java --jvm 21 --setup` + +* Periodically update to the latest Coursier version: + +```text +cs update cs +``` + +* Periodically update your executables by re-installing them, e.g.: +```text +cs install scalafmt +``` + + + +## 6. Windows Installation + +Coursier might not be able to install Java 21 on your system, so it's much +safer to install Java BEFORE installing Coursier: + +1\. **Install Chocolatey (if not already installed)** + +- Open PowerShell as Administrator. +- Run the following command to install Chocolatey: +``` +Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) +``` + +2\. **Install JDK 21 using Chocolatey** +``` +choco install openjdk --version 21 +``` + +Chocolatey also handles environment variable setup. +Once you finish, close the shell and open a new one. +Verify `JAVA_HOME` and `PATH` variables to ensure they are pointed to the JDK 21 installation. +Now if you install and run Coursier it should find your newly-installed JDK 21 rather than installing a JDK. + +3\. **Install and Run Coursier** + +- Follow the [Coursier Windows Installation Instructions](https://get-coursier.io/docs/cli-installation#windows). +- Run `cs setup`. +- Coursier should find your freshly-installed JDK 21, which you can check with: +``` +cs java -version +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..baf26b4f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,13 @@ +# Effect Oriented Programming + +Resources for the book *Effect Oriented Programming*. + +## [EBook](https://leanpub.com/effect-oriented-programming) + +## [Print Book]() + +## [Examples](https://github.com/EffectOrientedProgramming/examples) + +## [Book Repository](https://github.com/EffectOrientedProgramming/book) + +## [Error Reports](https://github.com/EffectOrientedProgramming/examples/issues) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..e0b41f7e --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,24 @@ +site_name: Effect Oriented Programming +site_url: https://EffectOrientedProgramming.com/ +site_description: Support Site for the Book +site_author: Bill Frasure, James Ward and Bruce Eckel +# repo_url: https://github.com/EffectOrientedProgramming/book/ + +nav: + - Home: index.md + - Guide: + - Installing Scala & Tools: guide/scalatools.md + - Running the Book Code: guide/examples.md + - About: + - Authors: about/authors.md + - License: about/license.md + +plugins: + - redirects: + redirect_maps: + 'resources/zio/sharing-layers-between-multiple-files.md': 'https://zio.dev/reference/test/sharing-layers-between-multiple-files/' + 'resources/zio/test-assertion-library.md': 'https://zio.dev/reference/test/assertions/' + 'resources/zio/docs.md': 'https://zio.dev/reference/' + 'resources/zio/whats-functional-programming-all-about.md': 'https://www.lihaoyi.com/post/WhatsFunctionalProgrammingAllAbout.html' + 'resources/zio/zio-config-docs-index.md': 'https://github.com/zio/zio-config/blob/master/docs/index.md' + 'resources/zio/compare-and-swap.md': 'https://en.wikipedia.org/wiki/Compare-and-swap' diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..e34f4d81 --- /dev/null +++ b/requirements.txt @@ -0,0 +1 @@ +mkdocs-redirects