Dev docs for profiling I tried to optimize build process so the docs can be built under 150ms. Currently, on my M1 Mac mini, it takes 180ms~210ms. I think it's too much for just 16 documents. I'm not good at profiling or optimization or whatever. I suck at looking at profiling result. What the fuck is bottom-up? But I have to profile in order to optimize further more. Luckily, Deno/V8's profiler is easy to use and call tree representation is intuitive even for beginers like me. Unfortunately, most of the process time is from third-party libraries. The most time consuming one was refractor (syntax highlighting) and the second was hast-util-to-html or mdast-from-markdown (or inner micromark). All of those are reasonable: refractor's "all" entrypoint (I willingfully choose this) contains every language syntax, thus it takes a lot of time loading and registering syntaxes. Seriealizing HTML and parsing Markdown are, well, time-consuming considering they are written in JavaScript, which is difficult to write performant string ops (esp. spatial efficiency). In its current form, the most impactful performance optimization I can think of is not emitting embed page until required. In order to do that, I have to make significant changes to how page builder handles build queue (or make one). While I found out there are no low-haning fruit for temporal optimization, I believe an experience and knowledge I gained from this should be noted and shared anyhow. So here it is.

Changes

1 changed files (+21/-3)

• docs/en/Internals/Development Guide.md
  • @@ -44,7 +44,9 @@ - Having both `docs/CLI.md` and `docs/cli.md`
    Other than that, use `snake_case` for file/directory names. - ## Formatting code + ## Development commands, scripts + + ### Formatting code Run this command on the repository root:
  • @@ -52,7 +54,7 @@ ```
    $ deno fmt ``` - ## Running unit tests + ### Running unit tests The most straightforward way to run the tests is to run this command on the repository root:
  • @@ -61,4 +63,20 @@ $ deno test --allow-read=. --allow-write=./filesystem_writer/.test
    ``` - If you omit the `--allow-read=.` permission, tests performing actual file I/O will be skipped. - - If you omit the `--allow-write=./filesystem_writer/.test` permission, tests performing actual file write will be skipped. + - If you omit the `--allow-write=./filesystem_writer/.test` permission, tests performing actual file write will be skipped. + + ### Profiling + + You can inspect (call-tree, memory, etc) using V8 Inspector Protocol via `--inspect-brk` flag. + Read more about the flag [here](https://dotland.deno.dev/manual@v1.33.1/basics/debugging_your_code). + + ``` + $ deno run --inspect-brk --allow-read=docs --allow-write=docs/.dist docs/build.ts + ``` + + The above command prints Inspector URL to your terminal. Open the URL with a debugger client supporting V8 Inspector Protocol, and hit the record button. + + You can replace `--inspect-brk` flag with `--inspect-wait` flag, if you don't want profiler. + + However, as Macana is short-lived program, you can't use the simple `--inspect` flag. + It's difficult to connect to the debugger during building this document, which is under 500ms even in GitHub Actions runner.