README
¶
Finch CLI
Local Development
This section describes how one can develop Finch CLI locally on macOS, build it, and then run it to test out the changes. The design ensures that the local development environment is isolated from the homebrew installation (i.e., we should not need to run make install to do local development).
Dependency Installation
This section installs the dependencies need to build and run finch. finch leverages several other pieces of technology to provide the platform elements which include lima, qemu and others. The application wraps numerous pieces of technology to provide one cohesive application.
It only needs to be done when the repository is just cloned.
make
Build
After you make some code changes, run the following command under the repository root to build an updated binary. It will generate a binary under ./_output/bin/finch.
make finch
Run
Spin up the VM if you haven't. Note that if it's your time to run finch vm init, it may require you to enter your root password because it needs to configure socket-vmnet, which need to be installed to privileged locations.
./_output/bin/finch vm init
Now you can run whatever command you want to test:
./_output/bin/finch ...
Config
A config file at $USER/.finch/finch.yaml will be generated on first-run. Currently, this config file has options for system resource limits for the VM that is used to run containers. These default limits are generated dynamically based on the resources available on the host system, but can be changed by manually editing the config file.
Currently, the options are:
- CPUs [int]: the amount of cores to dedicate to the VM (must be greater than 0, warning after exceeding max availbe on host)
- Memory [string]: the amount of RAM to dedicate to the VM (must be greater than 0, warning after exceeding max availbe on host)
For a full list of configuration options, check the struct here.
An example config.yaml looks like this:
cpus: 4
memory: 4GiB
Unit Testing
To run unit test locally, please run make test-unit. Please make sure to run the unit tests before pushing the changes.
Ideally each go file should have a test file ending with _test.go, and we should have as much test coverage as we can.
To check unit test coverage, run make coverage under root finch-cli root directory.
E2E Testing
Run these steps at the first time of running e2e tests
VM instance is not expected to exist before running e2e tests, please make sure to remove it before going into next step:
./_output/bin/finch vm stop
./_output/bin/finch vm remove
To run e2e test locally, please run make test-e2e. Please make sure to run the e2e tests or add new e2e tests before pushing the changes.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package main denotes the entry point of finch CLI.
|
Package main denotes the entry point of finch CLI. |
|
pkg
|
|
|
command
Package command invokes external commands.
|
Package command invokes external commands. |
|
config
Package config handles parsing and applying options from finch's config file.
|
Package config handles parsing and applying options from finch's config file. |
|
dependency
Package dependency allows for the creation of Dependencies and Dependency Groups, and provides functions to install these Groups.
|
Package dependency allows for the creation of Dependencies and Dependency Groups, and provides functions to install these Groups. |
|
dependency/vmnet
Package vmnet handles installation and configuration of dependencies needed for Lima's managed networking and port-forwarding to work, with minimal user interaction.
|
Package vmnet handles installation and configuration of dependencies needed for Lima's managed networking and port-forwarding to work, with minimal user interaction. |
|
flog
Package flog contains logging-related APIs.
|
Package flog contains logging-related APIs. |
|
fmemory
Package fmemory provides functions and methods to get memory information about the current system.
|
Package fmemory provides functions and methods to get memory information about the current system. |
|
fssh
Package fssh provides functions and methods to configure and create SSH connections.
|
Package fssh provides functions and methods to configure and create SSH connections. |
|
lima
Package lima provides common methods related to Lima.
|
Package lima provides common methods related to Lima. |
|
mocks
Package mocks is a generated GoMock package.
|
Package mocks is a generated GoMock package. |
|
path
Package path contains functions to find/calculate path used in the project.
|
Package path contains functions to find/calculate path used in the project. |
|
system
Package system contains interfaces for OS related APIs, intended to be used for dependency injection to facilitate unit testing.
|
Package system contains interfaces for OS related APIs, intended to be used for dependency injection to facilitate unit testing. |
|
version
Package version contains generated version number from GO build
|
Package version contains generated version number from GO build |