🗂️ FolSum

FolSum is a simple application for summarizing the contents of a directory. It counts each filetype by extension and displays those counts in a table. You can preview it here.

🖥️ Installation

todo: write installation section in README.md

This section is a work in progress, but for now, check out the Releases Page.

🖱️ Usage

Launch the program, select the directory that you'd like to summarize, and click "Summarize" in the left pane. A table with counts of each filetype will appear in the right pane.

🛠️ Contributing

🌳 Branch Naming Conventions

Branch names follow the pattern prefix / branch_name. In practice, this looks like goingforbrooke/folsum/tree / branch_prefix / branch_name.

The branch_prefix depends on the purpose of the branch, described in the table below. Every branch must have a prefix, except for main and dev, which can only be merged into.

For example, a branch that fixes a launch issue might look like fix/launch_broken and a branch that adds a green button might look like feat/green_button. This style is consistent with Git's repo/branch style and GitHub-style URLs.

Each branch prefix triggers different things in the CI/CD workflow.

❓	Prefix	Purpose	CI/CD Trigger
📦	main	Publish releases	Increment minor/patch version and publish a standard release
🛠️	dev	Development	Implicitly bump minor/patch version after --no-ff merge to main
✨	feat/*	Add features	Implicitly bump minor/patch version after --no-ff merge to dev, then main
🪲	fix/*	Fix bugs	Explicitly bump patch version after --no-ff merge to dev, then main
👷🏼‍️	cicd/*	Develop and test CI/CD pipelines	Immediately publish a draft release and skip bumping minor/patch version
📚	doc/*	Change README.md	Implicitly bump minor/patch version after --no-ff merge to dev, then main
🧹	internal/*	Refactoring and quality of life improvements	Implicitly bump minor/patch version after --no-ff merge to dev, then main

🔩 Dependencies

Adding dependencies with xtask looks a little different than normal.

For example, to add the chrono crate as a dependency to Folsum, use --package folsum.

$ user@host: cargo add --package folsum chrono

For example, to add the chrono crate as a dependency to the build tools, use --package xtask.

$ user@host: cargo add --package xtask chrono

🏁 xtask

$ user@host: cargo xtask build

📦 cargo build

Build for MacOS (Intel x86_64):

$ user@host: cargo build --release --target x86_64-apple-darwin
Finished release [optimized] target(s) in 0.06s

Build for MacOS (ARM64/Apple Silicone):

$ user@host: cargo build --release --target aarch64-apple-darwin
Finished release [optimized] target(s) in 0.08s

Build for MacOS (Intel x86_64 and ARM64/Apple Silicone):

$ user@host: cargo build --release --target x86_64-apple-darwin --target aarch64-apple-darwin
Finished release [optimized] target(s) in 0.08s

Create universal MacOS binary (MacOS only):

$ user@host: lipo -create -output target/release/folsum -arch x86_64 target/x86_64-apple-darwin/release/folsum -arch arm64 target/aarch64-apple-darwin/release/folsum

Check architectures on universal MacOS binary:

$ user@host lipo -archs target/release/bundle/osx/folsum.app/Contents/MacOS/folsum
x86_64 arm64

Build for Windows:

$ user@host: cargo build --release --target x86_64-pc-windows-gnu

🏗️ CI/CD

The MacOS build-release pipeline is triggered by pushes to the main branch and any branch that starts with cicd/.

The build creates a universal binary for MacOS by creating a binary for each processor architecture (aarch64-apple-darwin for Apple Silicon and x86_64-apple-darwin for Intel). These binaries are melded with lipo to create a MacOS universal binary. The lipo command is specific to MacOS runners, but there are cheaper alternatives.

We use Cargo Bundle to create an *.app bundle and plist file. Then we tell Cargo Bundle to skip building new binaries and place our universal binary (from the previous step) where Cargo Bundle expects to find it.

The final *.app bundle is codesigned and notarized so MacOS doesn't think that it's malware.

If the commit was pushed to the main branch, then we bump the minor version or the patch version. The type of bump depends on whether the last branch merged to dev starts with fix/*. If it does, then we use Cargo Edit to increment the SemVer patch version in Cargo.toml by one. Otherwise, we default to incrementing the minor version in Cargo.toml by one.

Whether the minor or patch version was incremented, the change to Cargo.toml's committed to the repo. Then we tag the commit with the new version number and use that tag to name the new release. It's imperative that the version changes for each release because release names must be unique. This ensures that previous releases aren't overwritten.

Otherwise, if the commit was pushed to a branch starting with cicd, then we skip incrementing the minor version. In addition, pushes to any non-main branch (including those starting with cicd) will create a "draft" release (which won't be visible to others in the FolSum repo's "Releases" page because it's a draft release) instead of a regular release. Note that this doesn't override the top-level branch filter-- builds are only triggered by pushes to main or branches that start with cicd. These draft releases won't fail when the release name (defined by the non-incremented SemVer tag) already exists. This makes it easy to hack on the CI/CD pipeline without messing up production builds.

📐 Design Decisions

👷🏼‍♀️ Xtask for Builds

On branch internal/xtask_postbuild, most of the project was moved from the root directory (folsum/) into a new subdirectory (folsum/folsum/) so the xtask pattern can be used for post-build actions. Build scripts like build.rs run before compilation, so it's not possible to bundle (MacOS universal) binaries into a .app deliverable with cargo build.

Placing a file named build.rs in the root of a package will cause Cargo to compile that script and execute it just before building the package. -- Rust docs

Post-build scripts are an ongoing discussion in the Rust community and xtask looks like the best solutionhttps://doc.rust-lang.org/cargo/reference/build-scripts.html#build-scripts apart from Github Actions. The xtask pattern is defined here, but we used this example to implement it because it's more up-to-date.

🐂 Tauri Bundler/Cargo Bundle for Bundling

Whether Folsum evolves to use Cargo Bundle or (continues to use) Tauri Bundler, post-build scripts will be necessary. Tauri Bundler is more mature with more supported platforms, but Cargo Bundle (from which Tauri Bundler is forked) is more Rust-centric. This is because Cargo Bunndle uses Cargo.toml for bundle configuration without using Tauri's CLI to fill missing values

🧟‍♀️ Xtask and Tauri Bundler Together

Since we're rolling our own build scripts in Rust, we use Tauri Bundler's API, which is very close to Cargo Bundle API, sans Cargo.toml configuration extraction. We might've stuck with the (initial) Cargo Bundle implementation if we had figured out the icon sizing issues sooner. Instead, we'll go with Tauri Bundler for now and slowly PR-patch our way back to Cargo Bundle.

As of v2.0.0, the Actions CI pipeline uses Cargo Bundle (via CLI) and the (local) xtask pipeline uses Tauri Bundle (via API interface).

Xtask requires no extra dependencies for implementing post-build actions. It uses what Cargo already offers. In the author's words,

Using external build systems and scripting languages can be useful, but using these technologies can result in inaccessible contributing experiences and potentially locking out valid development environments.

Since cargo is the tried and true build system for Rust (tested on multiple tiered targets), we can get the best of both worlds by using a small wrapper around it. Thus, cargo xtask exists to fill the gap; allowing for repository automation without needing to install another dependency.

🐭 Misc.

Apple's documentation on how to create a certificate signing request on MacOS

Reddit post on the difference between .pkg, .dmg, and .app

Possible lipo alternative written in Go

🔌 Compatibility

FolSum requires no external dependencies to run.

🙏🏻 Kudos

Readme format inspired by Make a README and awesome-readme.

Changelog format inspired by Keep a Changelog.

🛟 Support

If you need to contact the developers, then file an issue with one of these labels:

• 🪲 Bug: bug 🪲Something's busted
• ✨ Feature: feature ✨New feature or request
• 🙋🏼‍♀️ Question: question 🙋🏼‍♀️Further information is requested

🪪 License

Must be 16 or older and have an adult in the car during operation.