Merge pull request #1021 from UC-Davis-molecular-computing/dev

Dev

Author: dave-doty

.github/workflows/dart.yml

@@ -1,8 +1,8 @@
 name: Dart CI
 
-on:  
+on:
   pull_request:
-    types: [opened, synchronize, reopened, ready_for_review]
+    types: [ opened, synchronize, reopened, ready_for_review ]
 
 jobs:
   run_unit_tests:
@@ -11,27 +11,27 @@ jobs:
     runs-on: ubuntu-22.04
 
     steps:
-    - name: Setup Dart SDK Step 1
-      run: sudo apt-get update
-    - name: Setup Dart SDK Step 2
-      run: sudo apt-get install apt-transport-https
-    - name: Setup Dart SDK Step 3
-      run: sudo sh -c 'wget -qO- https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add -'
-    - name: Setup Dart SDK Step 4
-      run: sudo sh -c 'wget -qO- https://storage.googleapis.com/download.dartlang.org/linux/debian/dart_stable.list > /etc/apt/sources.list.d/dart_stable.list'
-    - name: Setup Dart SDK Step 5
-      run: wget -O /tmp/dart_2.13.4-1_amd64.deb https://storage.googleapis.com/dart-archive/channels/stable/release/2.13.4/linux_packages/dart_2.13.4-1_amd64.deb
-    - name: Setup Dart SDK Step 6
-      run: sudo apt install /tmp/dart_2.13.4-1_amd64.deb
-    - uses: actions/checkout@v3
-    - name: Install dependencies
-      run: PATH="$PATH:/usr/lib/dart/bin" pub get
-    - name: Run tests
-      run: PATH="$PATH:/usr/lib/dart/bin" pub run build_runner test
+      - name: Setup Dart SDK Step 1
+        run: sudo apt-get update
+      - name: Setup Dart SDK Step 2
+        run: sudo apt-get install apt-transport-https
+      - name: Setup Dart SDK Step 3
+        run: sudo sh -c 'wget -qO- https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add -'
+      - name: Setup Dart SDK Step 4
+        run: sudo sh -c 'wget -qO- https://storage.googleapis.com/download.dartlang.org/linux/debian/dart_stable.list > /etc/apt/sources.list.d/dart_stable.list'
+      - name: Setup Dart SDK Step 5
+        run: wget -O /tmp/dart_3.5.4-1_amd64.deb https://storage.googleapis.com/dart-archive/channels/stable/release/3.5.4/linux_packages/dart_3.5.4-1_amd64.deb
+      - name: Setup Dart SDK Step 6
+        run: sudo apt install /tmp/dart_3.5.4-1_amd64.deb
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: PATH="$PATH:/usr/lib/dart/bin" dart pub get
+      - name: Run tests
+        run: PATH="$PATH:/usr/lib/dart/bin" dart run build_runner test
 
   fail_if_pull_request_is_draft:
     if: github.event.pull_request.draft == true
     runs-on: ubuntu-18.04
     steps:
-    - name: Fails in order to indicate that pull request needs to be marked as ready to review and unit tests workflow needs to pass.
-      run: exit 1
+      - name: Fails in order to indicate that pull request needs to be marked as ready to review and unit tests workflow needs to pass.
+        run: exit 1

.github/workflows/dart_formatting.yml

@@ -1,8 +1,8 @@
 name: Dart Formatting
 
-on:  
+on:
   pull_request:
-    types: [opened, synchronize, reopened, ready_for_review]
+    types: [ opened, synchronize, reopened, ready_for_review ]
 
 jobs:
   check_formatting:
@@ -11,27 +11,27 @@ jobs:
     runs-on: ubuntu-22.04
 
     steps:
-    - name: Setup Dart SDK Step 1
-      run: sudo apt-get update
-    - name: Setup Dart SDK Step 2
-      run: sudo apt-get install apt-transport-https
-    - name: Setup Dart SDK Step 3
-      run: sudo sh -c 'wget -qO- https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add -'
-    - name: Setup Dart SDK Step 4
-      run: sudo sh -c 'wget -qO- https://storage.googleapis.com/download.dartlang.org/linux/debian/dart_stable.list > /etc/apt/sources.list.d/dart_stable.list'
-    - name: Setup Dart SDK Step 5
-      run: wget -O /tmp/dart_2.13.4-1_amd64.deb https://storage.googleapis.com/dart-archive/channels/stable/release/2.13.4/linux_packages/dart_2.13.4-1_amd64.deb
-    - name: Setup Dart SDK Step 6
-      run: sudo apt install /tmp/dart_2.13.4-1_amd64.deb
-    - uses: actions/checkout@v3
-    - name: Install dependencies
-      run: PATH="$PATH:/usr/lib/dart/bin" pub get
-    - name: Verify formatting
-      run: dart format -l 110 --output=none --set-exit-if-changed .
-      
+      - name: Setup Dart SDK Step 1
+        run: sudo apt-get update
+      - name: Setup Dart SDK Step 2
+        run: sudo apt-get install apt-transport-https
+      - name: Setup Dart SDK Step 3
+        run: sudo sh -c 'wget -qO- https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add -'
+      - name: Setup Dart SDK Step 4
+        run: sudo sh -c 'wget -qO- https://storage.googleapis.com/download.dartlang.org/linux/debian/dart_stable.list > /etc/apt/sources.list.d/dart_stable.list'
+      - name: Setup Dart SDK Step 5
+        run: wget -O /tmp/dart_3.5.4-1_amd64.deb https://storage.googleapis.com/dart-archive/channels/stable/release/3.5.4/linux_packages/dart_3.5.4-1_amd64.deb
+      - name: Setup Dart SDK Step 6
+        run: sudo apt install /tmp/dart_3.5.4-1_amd64.deb
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: PATH="$PATH:/usr/lib/dart/bin" dart pub get
+      - name: Verify formatting
+        run: PATH="$PATH:/usr/lib/dart/bin" dart format -l 110 --output=none --set-exit-if-changed .
+
   fail_if_pull_request_is_draft:
     if: github.event.pull_request.draft == true
     runs-on: ubuntu-18.04
     steps:
-    - name: Fails in order to indicate that pull request needs to be marked as ready to review and formatting workflow needs to pass.
-      run: exit 1
+      - name: Fails in order to indicate that pull request needs to be marked as ready to review and formatting workflow needs to pass.
+        run: exit 1

.github/workflows/gh-pages-dev.yml

@@ -19,8 +19,8 @@ jobs:
         with:
           ref: gh-pages
           path: gh-pages-repo
-        
-          
+
+
 
       - name: Setup Dart SDK Step 1
         run: sudo apt-get update
@@ -31,20 +31,20 @@ jobs:
       - name: Setup Dart SDK Step 4
         run: sudo sh -c 'wget -qO- https://storage.googleapis.com/download.dartlang.org/linux/debian/dart_stable.list > /etc/apt/sources.list.d/dart_stable.list'
       - name: Setup Dart SDK Step 5
-        run: wget -O /tmp/dart_2.13.4-1_amd64.deb https://storage.googleapis.com/dart-archive/channels/stable/release/2.13.4/linux_packages/dart_2.13.4-1_amd64.deb
+        run: wget -O /tmp/dart_3.5.4-1_amd64.deb https://storage.googleapis.com/dart-archive/channels/stable/release/3.5.4/linux_packages/dart_3.5.4-1_amd64.deb
       - name: Setup Dart SDK Step 6
-        run: sudo apt install /tmp/dart_2.13.4-1_amd64.deb
+        run: sudo apt install /tmp/dart_3.5.4-1_amd64.deb
 
       - name: Install dependencies
-        run: PATH="$PATH:/usr/lib/dart/bin" pub get
-        
+        run: PATH="$PATH:/usr/lib/dart/bin" dart pub get
+
       - name: Install webdev
-        run: PATH="$PATH:/usr/lib/dart/bin" pub global activate webdev
-      
+        run: PATH="$PATH:/usr/lib/dart/bin" dart pub global activate webdev
+
 
       - name: Build into gh-pages repo
-        run: PATH="$PATH:/usr/lib/dart/bin" pub global run webdev build -o web:gh-pages-repo/dev
-      
+        run: PATH="$PATH:/usr/lib/dart/bin" dart pub global run webdev build -o web:gh-pages-repo/dev
+
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3

.github/workflows/gh-pages.yml

@@ -17,8 +17,8 @@ jobs:
         with:
           ref: gh-pages
           path: gh-pages-repo
-      
-          
+
+
 
       - name: Setup Dart SDK Step 1
         run: sudo apt-get update
@@ -29,14 +29,14 @@ jobs:
       - name: Setup Dart SDK Step 4
         run: sudo sh -c 'wget -qO- https://storage.googleapis.com/download.dartlang.org/linux/debian/dart_stable.list > /etc/apt/sources.list.d/dart_stable.list'
       - name: Setup Dart SDK Step 5
-        run: wget -O /tmp/dart_2.13.4-1_amd64.deb https://storage.googleapis.com/dart-archive/channels/stable/release/2.13.4/linux_packages/dart_2.13.4-1_amd64.deb
+        run: wget -O /tmp/dart_3.5.4-1_amd64.deb https://storage.googleapis.com/dart-archive/channels/stable/release/3.5.4/linux_packages/dart_3.5.4-1_amd64.deb
       - name: Setup Dart SDK Step 6
-        run: sudo apt install /tmp/dart_2.13.4-1_amd64.deb
+        run: sudo apt install /tmp/dart_3.5.4-1_amd64.deb
       - name: Install dependencies
-        run: PATH="$PATH:/usr/lib/dart/bin" pub get
-        
+        run: PATH="$PATH:/usr/lib/dart/bin" dart pub get
+
       - name: Install webdev
-        run: PATH="$PATH:/usr/lib/dart/bin" pub global activate webdev
+        run: PATH="$PATH:/usr/lib/dart/bin" dart pub global activate webdev
 
 
       - name: Build into gh-pages repo
@@ -45,11 +45,11 @@ jobs:
         run: echo "VERSION=$(cat lib/src/constants.dart | grep  'const String CURRENT_VERSION = .*' | grep -oP '\d+\.\d+\.\d+')"  >> $GITHUB_ENV
       - name: Build into gh-pages-repo/VERSION
         run: |
-         if [ "$VERSION" != "" ]; then
-            PATH="$PATH:/usr/lib/dart/bin" pub global run webdev build -o web:gh-pages-repo/v$VERSION
-         else
-            echo "::warning deploying VERSION skipped because VERSION number could not be found"
-         fi
+          if [ "$VERSION" != "" ]; then
+             PATH="$PATH:/usr/lib/dart/bin" pub global run webdev build -o web:gh-pages-repo/v$VERSION
+          else
+             echo "::warning deploying VERSION skipped because VERSION number could not be found"
+          fi
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v3

.gitignore

@@ -4,6 +4,9 @@
 # Remove the following pattern if you wish to check in your lock file
 # pubspec.lock
 
+# I used this to add `// @dart=2.9` to the top of all dart files
+add-line.py
+
 # Conventional directory for build outputs
 build/
 

CONTRIBUTING.md

@@ -241,23 +241,23 @@ git checkout dev
 
 ### Installing Dart
 
-This project requires using Dart version **2.13**, not the latest version. Click on a dropdown below for installation instructions for your operating system.
+This project requires using Dart version **3.5.4**, not the latest version. Click on a dropdown below for installation instructions for your operating system.
 
 <!--TODO: Find a way to use code blocks with syntax highlighting inside <details>-->
 
 <details><summary><strong>Windows</strong></summary>
 First, install <a href="https://chocolatey.org/install">Chocolatey</a> if you haven't already. If <code>choco help</code> shows a help menu for using Chocolatey, then you've set it up correctly.
 
-Then, install Dart 2.13.4:
+Then, open a shell (cmd/Powershell) with Administrative privileges (go to Start type `cmd`, right-click on "Command Prompt", or type Powershell and right-click on "Powershell"; in both cases pick "Run as administrator") and install Dart 3.5.4:
 
 <pre>
-choco install dart-sdk --version 2.13.4
+choco install dart-sdk --version 3.5.4
 </pre>
 
 To stop Chocolatey from automatically updating Dart to the latest version, pin it:
 
 <pre>
-choco pin --name="'dart-sdk'" --version="'2.13.4'"
+choco pin --name="'dart-sdk'" --version="'3.5.4'"
 </pre>
 
 </details>
@@ -267,16 +267,16 @@ First, install <a href="https://brew.sh/">Homebrew</a> if you haven't already. I
 
 It may help to run `brew tap dart-lang/dart` first.
 
-Then, install Dart 2.13.4:
+Then, install Dart 3.5.4:
 
 <pre>
-brew install dart@2.13.4
+brew install dart@3.5.4
 </pre>
 
 To stop Homebrew from automatically updating Dart to the latest version, pin it:
 
 <pre>
-brew pin dart@2.13.4
+brew pin dart@3.5.4
 </pre>
 
 If running `dart` in a terminal now does not work, you may need to follow <a href="https://docs.brew.sh/FAQ#my-mac-apps-dont-find-homebrew-utilities">these instructions</a>.
@@ -292,17 +292,17 @@ wget -qO- https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo gpg --dea
 echo 'deb [signed-by=/usr/share/keyrings/dart.gpg arch=amd64] https://storage.googleapis.com/download.dartlang.org/linux/debian stable main' | sudo tee /etc/apt/sources.list.d/dart_stable.list
 </pre>
 
-Then, install Dart 2.13.4:
+Then, install Dart 3.5.4:
 
 <pre>
 sudo apt-get update
-sudo apt-get install dart=2.13.4
+sudo apt-get install dart=3.5.4
 </pre>
 
 To stop apt from automatically updating Dart to the latest version, hold it:
 
 <pre>
-sudo apt-mark hold dart=2.13.4
+sudo apt-mark hold dart=3.5.4
 </pre>
 
 </details>
@@ -314,15 +314,42 @@ After installing the Dart SDK, you should see a help menu when you run `dart`.
 Once you have installed Dart, install all the Dart dependencies (from the same directory `scadnano` into which the project was cloned by git):
 
 ```
-pub get
+dart pub get
+```
+
+Try running the unit tests like this:
+
+```
+dart run build_runner test
+```
+
+If the above command fails, it should be run as sudo or an administrator.
+
+It should report something like this after running the tests:
+
+```
+C:\Dropbox\git\scadnano>dart run build_runner test
+[INFO] Generating build script completed, took 248ms
+[INFO] Reading cached asset graph completed, took 332ms
+[INFO] Checking for updates since last build completed, took 474ms
+[INFO] Running build completed, took 17.0s
+[INFO] Caching finalized dependency graph completed, took 367ms
+[INFO] Creating merged output dir `C:\Users\pexat\AppData\Local\Temp\build_runner_test1a56df4\` completed, took 3.0s
+[INFO] Writing asset manifest completed, took 18ms
+[INFO] Succeeded after 20.4s with 933 outputs (1003 actions)
+Running tests...
+
+Building package executable... (4.0s)
+Built test:test.
+00:11 +491 ~2: All tests passed!
 ```
 
 ### Installing `webdev`
 
-This project uses an older version of the `webdev` tool, not the latest version, to build and serve the web app. Install it with:
+`webdev` is used to run a local server for running scadnano in your browser for testing. Install it with:
 
 ```
-pub global activate webdev 2.5.9
+dart pub global activate webdev
 ```
 
 Note that often a message like this appears:
@@ -350,16 +377,14 @@ server](https://dart.dev/tools/webdev#serve).
 
 Sometimes it may be necessary to clean out the generated files and cache if this has an error. See the file `clean.sh`, which has this line: `dart run build_runner clean`. Also see `remove_g.sh`, which removes all `.g.dart` files from the project, which can also help to fix compilation errors.
 
-If that does not work, try `dart run build_runner clean --delete-conflicting-outputs`.
+If that does not work, try `dart run build_runner build --delete-conflicting-outputs`, and then run `webdev serve`.
 
 Running `webdev serve --release` will compile the project in production mode (instead of development mode), which is claimed to be faster in principle if you are not doing development and just want to run scadnano offline.
 However, in scadnano, it doesn't appear to make a big difference whether development or production mode is used.
 The webdev program will tell you which URL to enter in your browser; it will be something like
 
 ```
-
 [INFO] Serving `web` on http://127.0.0.1:8080
-
 ```
 
 Sometimes you may see an unexpected compilation error even if you haven't changed the code from a state where it was compiling okay. If you've really tried to fix an error and it doesn't seem to be due to a mistake in the code, then as a last resort, try running `./clean.sh`. This will clear out cached files and `.g.dart` files, which can sometimes become stale and need to be regenerated. If you run `./clean.sh`, and the project still does not compile, then it is a genuine syntax error that needs to be fixed.
@@ -384,12 +409,31 @@ extensions helpful for debugging and profiling.
 
 ### Running Tests
 
-Unit tests are contained in the [test](test/) directory.
+Unit tests are contained in the [test](test/) directory. To run them all type `dart run build_runner test`.
+
+You can also run one file at a time like this: 
+
+```
+dart run build_runner test -- test\assign_dna_unit_test.dart
+```
+
+or even one test at a time like this:
+
+```
+dart run build_runner test -- test\assign_dna_unit_test.dart --plain-name "Assign/remove dna test:  AssignDNA"
+```
+
+That can be useful for debugging a test using the Chrome browser devtools like this:
+
+```
+dart run build_runner test -- test\assign_dna_unit_test.dart --plain-name "Assign/remove dna test:  AssignDNA" -P debug
+```
+
+This opens a browser and lets you set a breakpoint if you open browser dev tools (type Ctrl+Shift+I). It can be a bit hard to find the files, look here:
+
+![alt text](images/location-of-scadnano-sources-unit-testing.png)
+
 
-The repository provides a test script [test.sh](test.sh), which
-provides common utilities for running unit tests. All unit tests
-can be run by `bash test.sh`. To see more options, run
-`bash test.sh -h`.
 
 Please add unit tests whenever possible. Currently, there are unit
 tests for [Redux reducers](test/reducer_test.dart) and a few tests for