document some development decisions

marph91 · Oct 20, 2024 · 1c42ff3 · 1c42ff3
1 parent 8edf5d4
commit 1c42ff3
Show file tree

Hide file tree

Showing 4 changed files with 85 additions and 21 deletions.
diff --git a/docs/contributing/design_decisions.md b/docs/contributing/design_decisions.md
diff --git a/docs/contributing/development_considerations.md b/docs/contributing/development_considerations.md
@@ -0,0 +1,73 @@
+# Development Considerations
+
+## Why Markdown?
+
+To provide a flexible base for migrating your notes to the app of your choice.
+
+## Why enlighten and not tqdm for progress bars?
+
+enlighten did integrate easier with pythons logging.
+
+## Sort all iterators with arbitrary order
+
+Reproducibility is more important than memory usage and speed.
+
+```python
+# good
+for item in sorted(file_or_folder.iterdir()):
+
+# bad
+for item in file_or_folder.iterdir():
+```
+
+## Why pyinstaller and not nuitka?
+
+I did have a bit experience in setting up pyinstaller. The size of the final executable seems to be [much smaller with pyinstaller](https://github.com/Nuitka/Nuitka/issues/926), too.
+
+## Why is the executable so large?
+
+Pandoc is included and is standalone ~144 MB large. This has the biggest impact on the size. The module sizes in particular can be analyzed by using the following code snippet in the pyinstaller spec file:
+
+```python
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.datas,
+    strip=False,
+    upx=True,
+    upx_exclude=[],
+    name='jimmy_cli',
+)
+```
+
+The resulting files can be listed and ordered by size by:
+
+```bash
+> du -lh dist/jimmy_cli | sort -h
+8,0K    dist/jimmy_cli/_internal/setuptools/_vendor/jaraco/text
+12K     dist/jimmy_cli/_internal/setuptools/_vendor/jaraco
+24K     dist/jimmy_cli/_internal/cryptography-43.0.3.dist-info/license_files
+24K     dist/jimmy_cli/_internal/wheel-0.44.0.dist-info
+40K     dist/jimmy_cli/_internal/Markdown-3.7.dist-info
+40K     dist/jimmy_cli/_internal/setuptools/_vendor/importlib_metadata-8.0.0.dist-info
+56K     dist/jimmy_cli/_internal/setuptools/_vendor
+60K     dist/jimmy_cli/_internal/cryptography-43.0.3.dist-info
+60K     dist/jimmy_cli/_internal/markupsafe
+60K     dist/jimmy_cli/_internal/setuptools
+108K    dist/jimmy_cli/_internal/ossl-modules
+164K    dist/jimmy_cli/_internal/puremagic
+288K    dist/jimmy_cli/_internal/charset_normalizer
+2,4M    dist/jimmy_cli/_internal/yaml
+11M     dist/jimmy_cli/_internal/cryptography
+11M     dist/jimmy_cli/_internal/cryptography/hazmat
+11M     dist/jimmy_cli/_internal/cryptography/hazmat/bindings
+15M     dist/jimmy_cli/_internal/lib-dynload
+144M    dist/jimmy_cli/_internal/pypandoc
+144M    dist/jimmy_cli/_internal/pypandoc/files
+213M    dist/jimmy_cli/_internal
+262M    dist/jimmy_cli
+```
+
+## Why cryptography and not pycryptodome?
+
+They worked both at the first implementation. `cryptography` made a slightly better impression, so it was chosen.
diff --git a/jimmy_cli.spec b/jimmy_cli.spec
@@ -63,3 +63,14 @@ exe = EXE(
     codesign_identity=None,
     entitlements_file=None,
 )
+
+# only needed for size analysis
+# coll = COLLECT(
+#     exe,
+#     a.binaries,
+#     a.datas,
+#     strip=False,
+#     upx=True,
+#     upx_exclude=[],
+#     name='jimmy_cli',
+# )
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -94,3 +94,4 @@ nav:
   - Contributing:
     - How to Contribute?: contributing/contributing.md
     - More Note Apps: contributing/more_note_apps.md
+    - Development Considerations: contributing/development_considerations.md