nimv2 full migration: round 2

.github/scripts/docs.nims

@@ -19,11 +19,10 @@ let
     --git.url:https://github.com/noahehall/nim \
     --hints:off \
     --index:on \
-    --multimethods:on \
+    --outdir:{docsDir} \
     --project \
-    --threads:on \
     --verbosity:0 \
-    --outdir:{docsDir} \
+    --warnings:off \
     """
 
 cd rootDir
@@ -52,6 +51,14 @@ proc createSourceDocs: (string, int) =
   except OSError:
     ("failed to create documentation", 1)
 
+proc createSourceDocsIndex: (string, int) =
+  echo "create user-serachable index HTML"
+  try:
+    fmt"buildIndex -o:{rootDir/docsDir}/theindex.html {rootDir / docsDir}".selfExec
+    ("user-searchable index HTML created", 0)
+  except OSError:
+    ("failed to user-searchable index", 1)
+
 proc createTestResults: (string, int) = createTestResultsHtml()
 
 proc createDependencyGraphs: (string, int) =
@@ -68,7 +75,7 @@ proc mvFilesToHtmlDocsDir: (string, int) =
     for output in @[
       rootDir / "src/bookofnim.dot",
       rootDir / "src/bookofnim.png",
-      rootDir / "testresults.html" # TODO think this broke viewing testresults in github pages
+      # rootDir / "testresults.html" # TODO(noah) think this broke viewing testresults in github pages
     ]: output.mvFile rootDir / docsDir / output.extractFilename
     ("documentation moved to htmldocs dir", 0)
   except CatchableError:
@@ -79,6 +86,7 @@ when isMainModule:
     installDeps,
     deletePrevdocs,
     createSourceDocs,
+    createSourceDocsIndex,
     createDependencyGraphs,
     createTestResults,
     mvFilesToHtmlDocsDir # must occur last

README.md

@@ -16,21 +16,28 @@
 
 - fullstack is a first principle for us; nim redefines what that means
 - many application developers are moving to/incorporating rust/go in their stack; suspend judgment and consider nim for (many, but definitely) these reasons
+- first-class features
   - [cross compile applications](https://nim-lang.org/docs/nimc.html#crossminuscompilation)
   - [cross platform scripts](https://nim-lang.org/docs/nims.html#benefits)
   - [robust application & script configuration](https://nim-lang.org/docs/parsecfg.html)
-  - [documentation is a first class citizen](https://nim-lang.org/docs/docgen.html)
+  - [documentation + html generation](https://nim-lang.org/docs/docgen.html)
     - [with first class support for reStructured text](https://docutils.sourceforge.io/docs/user/rst/quickref.html)
-  - [testing is a first class citizen](https://nim-lang.github.io/Nim/testament.html)
+  - [Holistic Test Suite](https://nim-lang.github.io/Nim/testament.html)
+    - TODO add unittest here even tho we dont use it
     - [with html reports](https://noahehall.github.io/nim/htmldocs/testresults.html)
     - [and valgrind integration for memory leaks](https://valgrind.org/)
-  - [first class support for postgres, mysql](https://nim-lang.org/docs/lib.html#impure-libraries-database-support)
-    - [including a generic ODBC wrapper for other dbs](https://nim-lang.org/docs/db_odbc.html)
   - [future proof design philisophy](https://www.youtube.com/watch?v=aDi50K_Id_k)
     - [with ergonomic APIs](https://nim-lang.org/docs/apis.html)
   - [various pragmas to customize, restrict and enhance the compiler and runtime](https://nim-lang.github.io/Nim/manual.html#pragmas)
-  - [community forum](https://forum.nim-lang.org/)
   - [spiderman's uncle](https://nim-lang.org/docs/tut3.html)
+- core-developer supported features
+  - [core-developer support for postgres, mysql](https://nim-lang.org/docs/lib.html#impure-libraries-database-support)
+    - [including a generic ODBC wrapper for other dbs](https://nim-lang.org/docs/db_odbc.html)
+  - TODO: i think the docs are still under nimlang, but the packages have moved to nimble
+    - add channels to this list
+- community driven
+  - [community-driven forum](https://forum.nim-lang.org/)
+  - TODO add the links to the other places
 
 ## recommended ramp up
 
@@ -128,6 +135,9 @@ internal
 
 nimlang
 
+- [AAA: nims index ctrl f-it](https://nim-lang.github.io/Nim/theindex.html)
+- [stable (i.e. 1.6\*)](https://nim-lang.org/docs/manual.html)
+- [v2 (i.e. >= 1.9.3)](https://nim-lang.github.io/Nim/manual.html)
 - [std library](https://nim-lang.org/docs/lib.html)
 - [nim manual](https://nim-lang.org/docs/manual.html)
 - [api design](https://nim-lang.org/docs/apis.html)

bookofnim.nimble

@@ -1,9 +1,11 @@
 from strutils import unindent
 import os
 
+const nimv = "1.9.3" ## sync on nim version
+
 # Package
 
-version       = "1.9.3" # syncd to nim version
+version       = nimv
 author        = "noahehall"
 description   = """
   book of nim: bow to the crown
@@ -15,7 +17,7 @@ srcDir        = "src"
 
 # Dependencies
 
-requires "nim >= 1.6.12"
+requires "nim >= " & nimv
 
 # Tasks
 
@@ -27,9 +29,10 @@ task copyGitHooks, "copies .github/hooks to .git/hooks":
   let fromDir = currentSourcePath() / ".." / ".github/hooks"
   for kind, path in fromDir.walkDir:
     if kind == pcFile and path[(path.len - 3) .. ^1] == ".sh":
-      echo "installing git hook: ", path.lastPathPart
       # git hooks dont have file extensions
-      path.cpFile toDir / path.lastPathPart[0 .. ^4]
+      let githook = path.lastPathPart[0 .. ^4]
+      echo "installing git hook: ", githook
+      path.cpFile toDir / githook
 
 
 task postclone, "executes post-repo-clone tasks":

config.nims

@@ -1,40 +1,108 @@
-# --colors:on # breaks vscode run code extension
-# --experimental:codeReordering dont use or fear the amount of logs it produces
-# FYI: hint/warningAsError requires switch() syntax
+discard """
+- This config aims to provide sensible defaults for web applications
+- push & pop specific pragmas in source when required, e.g. hint[Name]:off
 
---assertions:off
+the available environments include:
+- ENV=DEV: relaxes strict mode to allow for active development of features
+- ENV=PERF: danger mode
+- ENV=SIZE: reduced application size
+- ENV=SPEED: increased application speed
+- else uses --define:release
+
+the following envvars, if set to any value, will enable additional settings
+- CI: no parallel + force builds with verbosity set to 2
+- TEST: stacktraces turned on with verbosity set to 2
+  - see tests/config.nims for more (we borrowed heavily from nim's test config.nims)
+
+the following compiler switches are set for all environments focusing on
+developing applications with nim in a ghetto `strict` mode; in particular
+- all deprecations are errors
+- hints promoting good coding hygine are turned into errors
+- warnings that could materialize into bugs are turned into errors
+- nimPreviewSlimSystem is set to remove deprecated symbols and other things
+
+The aforementioned settings will disrupt your development velocity as you transition.
+depending on the size of your code base and deviation from `strict` standards
+will likely require major refactoring
+
+FYI:
+- --colors:on > breaks vscode run code extension
+- --experimental:codeReordering > will be replaced with a better solution in the future
+- --experimental:notnil > prefer strictNotNil unless your consuming unreliable packages
+  - however strictNotNil currently throws on nim source, so we use notnil
+- [hint|warning][AsError] > requires switch() syntax in configs
+- the following are removed until https://github.com/noahehall/nim/issues/40
+  --experimental:views
+  --experimental:strictCaseObjects
+  switch("warningAsError", "BareExcept:on")
+  switch("warningAsError", "ProveInit:on")
+  switch("warningAsError", "ResultUsed:on")
+  switch("warningAsError", "Uninit:on")
+- the following require more time to understand impact and usecase
+  - --define:useRealtimeGC # @see https://nim-lang.github.io/Nim/refc.html
+"""
+
+--assertions:off # should only be enabled in dev, use doAssert for hard checks
 --checks:on
 --debugger:native
 --deepcopy:on # required for mm:orc/arc
+--define:futureLogging
+--define:nimPreviewCstringConversion
+--define:nimPreviewSlimSystem
 --define:nimStrictDelete
 --define:release
 --define:ssl
 --define:threadsafe
 --errorMax:1
---experimental:strictEffects
---forceBuild:on
+--experimental:callOperator
+--experimental:dotOperators
+--experimental:flexibleOptionalParams
+--experimental:notnil
+--experimental:parallel
+--experimental:strictDefs
+--experimental:strictFuncs
 --hints:on
---mm:orc
+--mm:orc # required for async apps, else use arc
 --multimethods:on
 --panics:on
 --parallelBuild:0
+--spellSuggest
 --stackTraceMsgs:off
---styleCheck:error # can push specific pragmas, e.g. hint[Name]:off
---threads:on
+--styleCheck:error
 --tlsEmulation:on
 --unitsep:on # ASCII unit separator between error msgs
 --verbosity:0
 --warnings:on
-switch("hint","GlobalVar:off") # spams u to death
+switch("hint", "CC:off")
+switch("hint", "CodeBegin:off")
+switch("hint", "CodeEnd:off")
+switch("hint", "CondTrue:off")
+switch("hint", "GCStats:off")
+switch("hint", "GlobalVar:off") # spams u to death
+switch("hint", "Link:off")
+switch("hint", "Path:off")
+switch("hint", "Processing:off")
+switch("hint", "Success:off")
+switch("hintAsError", "ConvFromXtoItselfNotNeeded:on")
+switch("hintAsError", "ConvToBaseNotNeeded:on")
 switch("hintAsError", "DuplicateModuleImport:on")
+switch("hintAsError", "LineTooLong:on")
 switch("hintAsError", "Performance:on")
 switch("hintAsError", "XDeclaredButNotUsed:on")
+switch("warningAsError", "CannotOpenFile:on")
+switch("warningAsError", "CastSizes:on")
 switch("warningAsError", "ConfigDeprecated:on")
+switch("warningAsError", "CStringConv:on")
 switch("warningAsError", "Deprecated:on")
+switch("warningAsError", "EachIdentIsTuple:on")
+switch("warningAsError", "EnumConv:on")
 switch("warningAsError", "GcUnsafe:on")
 switch("warningAsError", "HoleEnumConv:on")
-switch("warningAsError", "ResultUsed:on")
+switch("warningAsError", "OctalEscape:on")
+switch("warningAsError", "SmallLshouldNotBeUsed:on")
+switch("warningAsError", "UnreachableElse:on")
 switch("warningAsError", "UnusedImport:on")
+
 case getCommand():
   of "c", "cc", "cpp", "objc":
     --lineDir:on
@@ -62,34 +130,29 @@ case getEnv "ENV":
     --danger
   of "SIZE":
     # @see https://github.com/ee7/binary-size
-    --checks:off
+    --define:useMalloc
     --opt:size
     --passC:"-flto"
     --passL:"-flto"
   of "SPEED":
-    --checks:off
     --opt:speed
     --passC:"-flto"
     --passL:"-s"
   else: discard
 
+case getEnv "ENV":
+  of "SIZE", "SPEED", "PERF":
+    --checks:off
+    --hints:off
+    --lineDir:off
+    --lineTrace:off
+    --stackTrace:off
+    --warnings:off
+  else: discard
+
 case existsEnv "CI":
   of true:
+    --forceBuild:on
     --parallelBuild:1
     --verbosity:2
   else: discard
-
-when (NimMajor, NimMinor, NimPatch) <= (1,6,12):
-  # throws in v2, maybe its no longer experimental?
-  --experimental:implicitDeref
-  # throws on nim source code
-  # @see https://github.com/nim-lang/Nim/issues/21713
-  switch("hintAsError", "DuplicateModuleImport:off")
-  switch("hintAsError", "Performance:off")
-  switch("hintAsError", "XDeclaredButNotUsed:off")
-  switch("warningAsError", "Deprecated:off")
-  switch("warningAsError", "HoleEnumConv:off") # only in ci on nim source
-  switch("warningAsError", "UnusedImport:off") # only in ci on nim source
-else:
-  --define:futureLogging
-  switch("warningAsError", "CastSizes:on")