Merge changes from main back to dev

.github/workflows/gh-pages.yml

@@ -0,0 +1,21 @@
+name: Documentation Deploy
+on:
+  push:
+    branches:
+      - main
+jobs:
+  docs:
+    concurrency: ci-${{ github.ref }}
+    runs-on: ubuntu-latest
+    container: nimlang/nim
+    steps:
+    - uses: actions/checkout@v3
+    - run: git config --global --add safe.directory "$(pwd)"
+    - run: nimble -y doc --index:on --out:docs --project src/playdate/api.nim
+    - run: cp docs/api.html docs/index.html
+    - name: Deploy documents
+      uses: peaceiris/actions-gh-pages@v3
+      if: ${{ !env.ACT }}
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs

.gitignore

@@ -6,6 +6,7 @@ htmldocs/
 src/tests/
 pdex.bin
 *.pdx
+docs
 tests/source/pdxinfo
 
 # macOS general

README.md

@@ -116,6 +116,12 @@ complete the build. This includes creating a `pdxinfo` file automatically, updat
 `config.nims`, and adding entries to your `.gitignore`. If you don't want this behavior, you
 can add the `--no-auto-config` flag, which will disable this.
 
+### Custom pdxinfo values
+
+Running `pdn` will automatically generate a `pdxinfo` file based on the project
+details in your packages `nimble` file. If you need to customize these values, you can
+add a `pdxinfo` file to the root of your package.
+
 ## Examples
 
 The example project `playdate_example` also contains VSCode launch configurations to build, start and debug your Nim application from the editor.

src/pdn.nim

@@ -1,5 +1,5 @@
 import std/[parseopt, strutils, os, macros, options]
-import playdate/build/[utils, actions]
+import playdate/build/[utils, actions, nimbledump]
 
 type
     BuildCommand = enum simulate, simulator, device, clean, bundle

src/playdate/build/actions.nim

@@ -1,4 +1,5 @@
-import std/[sequtils, strutils, os, times, strformat, osproc, sets, json, jsonutils], utils
+import std/[sequtils, strutils, os, strformat, osproc, sets, json]
+import utils, pdxinfo, nimbledump
 
 type
     BuildKind* = enum SimulatorBuild, DeviceBuild
@@ -10,18 +11,6 @@ type
         dump*: NimbleDump
         noAutoConfig*: bool
 
-    NimbleDump* = ref object
-        ## The data pulled from running `nimble dump --json`
-        name*, version*, nimblePath*, author*, desc*, license*: string
-
-proc getNimbleDump*(): NimbleDump =
-    ## Executes nimble with the given set of arguments
-    let (output, exitCode) = execCmdEx("nimble dump --json")
-    if exitCode != 0:
-        echo output
-        raise BuildFail.newException(fmt"Unable to extract nimble dump for package")
-    return parseJson(output).jsonTo(NimbleDump, Joptions(allowExtraKeys: true))
-
 proc exec*(command: string, args: varargs[string]) =
     ## Executes nimble with the given set of arguments
     let process = startProcess(
@@ -89,47 +78,12 @@ proc updateConfig(conf: PlaydateConf) =
 
     "configs.nims".fileAppend(fmt"\n\n# Added by pdn\nimport {configFile}\n")
 
-proc writePdxInfo(conf: PlaydateConf) =
-    ## Writes the pdx info file
-
-    let buildId = now().format("yyyyMMddhhmmss")
-
-    let (output, exitCode) = execCmdEx("git rev-parse HEAD")
-    let commit = if exitCode == 0: output[0..<8] else: conf.dump.version
-
-    let cartridgeName = conf.dump.name
-        .replace("_", " ")
-        .split(" ")
-        .map(proc(s: string): string = s.capitalizeAscii())
-        .join(" ")
-    let bundleAuthor = conf.dump.author
-        .toLower()
-        .replace(" ", "")
-        .replace("-", "")
-        .replace("_", "")
-    let bundleProjectName = conf.dump.name
-        .toLower()
-        .replace(" ", "")
-        .replace("-", "")
-        .replace("_", "")
-
-    let pdx = fmt"""
-        name={cartridgeName}
-        author={conf.dump.author}
-        description={conf.dump.desc}
-        bundleId=com.{bundleAuthor}.{bundleProjectName}
-        imagePath=launcher
-        version={commit}
-        buildNumber={buildId}
-        """.dedent()
-
-    createDir("source")
-    writeFile("source" / "pdxinfo", pdx)
-
 proc configureBuild*(conf: PlaydateConf) =
     if not conf.noAutoConfig:
         conf.updateConfig
-        conf.writePdxInfo
+        echo "Writing pdxinfo"
+        conf.dump.toPdxInfo.join(readPdx("./pdxinfo")).write
+        echo "Updating gitignore"
         conf.updateGitIgnore
 
 proc bundlePDX*(conf: PlaydateConf) =

src/playdate/build/nimbledump.nim

@@ -0,0 +1,14 @@
+import std/[strutils, strformat, osproc, json, jsonutils], utils
+
+type
+    NimbleDump* = ref object
+        ## The data pulled from running `nimble dump --json`
+        name*, version*, nimblePath*, author*, desc*, license*: string
+
+proc getNimbleDump*(): NimbleDump =
+    ## Executes nimble with the given set of arguments
+    let (output, exitCode) = execCmdEx("nimble dump --json")
+    if exitCode != 0:
+        echo output
+        raise BuildFail.newException(fmt"Unable to extract nimble dump for package")
+    return parseJson(output).jsonTo(NimbleDump, Joptions(allowExtraKeys: true))

src/playdate/build/pdxinfo.nim

@@ -0,0 +1,55 @@
+import std/[os, parsecfg, streams, strutils, strformat, times, osproc], nimbledump
+
+type PdxInfo* = object
+    ## Details used to populate the pdxinfo file
+    name*, author*, description*, bundleId*, imagePath*, version*, buildNumber*: string
+
+proc `$`*(pdx: PdxInfo): string =
+    for key, value in pdx.fieldPairs:
+        if value != "":
+            result &= key & "=" & value & "\n"
+
+proc write*(pdx: PdxInfo) =
+    ## Writes the pdxinfo file
+    createDir("source")
+    writeFile("source" / "pdxinfo", $pdx)
+
+proc join*(a, b: PdxInfo): PdxInfo =
+    ## Combins two PdxInfo instances
+    result = a
+    for current, override in fields(result, b):
+        if override != "":
+            current = override
+
+proc parsePdx*(data: Stream, filename: string): PdxInfo =
+    ## Parses a pdx config from a string
+    let dict = loadConfig(data, filename)
+    for key, value in result.fieldPairs:
+        value = dict.getSectionValue("", key)
+
+proc readPdx*(path: string): PdxInfo =
+    ## Creates a pdx by reading a local pxinfo file
+    if fileExists(path):
+        return parsePdx(newFileStream(path), path)
+
+proc gitHashOrElse(fallback: string): string =
+    let (output, exitCode) = execCmdEx("git rev-parse HEAD")
+    return if exitCode == 0: output[0..<8] else: fallback
+
+proc toPdxInfo*(
+    dump: NimbleDump,
+    version: string = gitHashOrElse(dump.version),
+    buildNumber: string = now().format("yyyyMMddhhmmss")
+): PdxInfo =
+    ## Creates a base PdxInfo file
+    result.name  = dump.name
+    result.author = dump.author
+    result.description = dump.desc
+
+    let bundleIdPkg = dump.author.toLower().replace(" ", "").replace("-", "").replace("_", "")
+    let bundleIdName = dump.name.replace(" ", "").toLowerAscii()
+    result.bundleId = fmt"com.{bundleIdPkg}.{bundleIdName}"
+    result.imagePath = "launcher"
+    result.version = version
+    result.buildNumber = buildNumber
+

tests/t_pdxinfo.nim

@@ -0,0 +1,69 @@
+import std/[unittest, strutils, streams], playdate/build/[pdxinfo, nimbledump]
+
+suite "Pdxinfo generation":
+
+    test "Produce a default pdxinfo from a nimble dump":
+        let dump = NimbleDump(
+            name: "Lorem Ipsum",
+            version: "0.0.0",
+            nimblePath: "/path/to/nimble",
+            author: "Twas Brillig",
+            desc: "A thing",
+            license: "MIT",
+        )
+
+        check($dump.toPdxInfo("1.2.3", "20250216") == """
+            name=Lorem Ipsum
+            author=Twas Brillig
+            description=A thing
+            bundleId=com.twasbrillig.loremipsum
+            imagePath=launcher
+            version=1.2.3
+            buildNumber=20250216
+            """.dedent())
+
+    test "Read a PDXInfo from a stream":
+        let pdx = newStringStream("""
+            name=Lorem Ipsum
+            author=Twas Brillig
+            description=A thing
+            bundleId=com.twasbrillig.loremipsum
+            imagePath=launcher
+            version=1.2.3
+            buildNumber=20250216
+            """).parsePdx("[stream]")
+
+        check($pdx == """
+            name=Lorem Ipsum
+            author=Twas Brillig
+            description=A thing
+            bundleId=com.twasbrillig.loremipsum
+            imagePath=launcher
+            version=1.2.3
+            buildNumber=20250216
+            """.dedent())
+
+    test "Join together multiple pdxinfo objects":
+        let pdx1 = PdxInfo(
+            name: "Lorem Ipsum",
+            description: "A thing",
+            imagePath: "launcher",
+            version: "1.2.3",
+            buildNumber: "20250216",
+        )
+
+        let pdx2 = PdxInfo(
+            author: "Twas Brillig",
+            bundleId: "com.twasbrillig.loremipsum",
+            version: "3.4.5",
+        )
+
+        check($join(pdx1, pdx2) == """
+            name=Lorem Ipsum
+            author=Twas Brillig
+            description=A thing
+            bundleId=com.twasbrillig.loremipsum
+            imagePath=launcher
+            version=3.4.5
+            buildNumber=20250216
+            """.dedent())