.TH C3VM 09/07/2025
.SH NAME
c3vm \- a c3c version manager


.SH SYNOPSIS
.B c3vm
[status|list|install|enable|add-local|update|remove|use]


.SH DESCRIPTION
This manpage documents the use (and some of the workings) of this version
manager for c3c (the compiler for C3).
It is a bash script that can install and manage versions of the compiler.
It does so by grabbing releases from github or even compile it from scratch,
and symlink the resulting binary to $HOME/.local/bin/c3c.

Most commands that have to do with "selecting" a certain version support the
same flags as the 'install' subcommand.


.SH SUBCOMMANDS
.IP status
Shows the currently enabled compiler with type (prebuilt/compiled).
For prebuilts it then differentiates between a prerelease or a release, for
compiled versions it shows the remote/local and git-rev (branch, tag or commit).
Both also differentiate between debug or release builds.

.IP list
Lists the installed compilers or the versions available on GitHub with --available.

.IP install
Install a version of the compiler.
By default it grabs the specified version (default "latest") from Github, but
this can be overriden with flags (see help-page).

.IP enable
Enable an already installed version by symlinking it.

.IP add-local
Check in a local repository into c3vm so that it can be used like you'd use a
git-remote to build from source.

.IP update
Update the currently enabled compiler. With flags this can also update other
installed versions of the compiler.

.IP remove
Remove installed versions of the compiler. Local repositories will not actually
be removed, but just unlinked from c3vm.

.IP use
Use a specific version to compile your project.


.SH EXAMPLES
.PP
Install and enable latest stable release
.RS 4
c3vm install
.RE

.PP
Install a specific version but do not enable it
.RS 4
c3vm install --dont-enable v0.6.8
.RE

.PP
Install debug compiler from source from a fork
.RS 4
c3vm install --from-source --remote bwindey/c3c --debug
.RE

.PP
Use a previous version for a single time
.RS 4
c3vm use v0.7.1 -- compile-run my_code.c3
.RE


.SH DIRECTORY LAYOUT
The installed compilers are stored under $XDG_DATA_HOME/c3vm/, where
$XDG_DATA_HOME defaults to $HOME/.local/share/ if it isn't set.
Inside that directory they are stored like this:
.nf
$XDG_DATA_HOME/c3vm/
├── git/
│   ├── local/
│   │   └── own_local -> /some/path/to/local/c3c/
│   └── remote/
│       ├── c3lang_c3c/
│       └── bwindey_c3c/
│           ├── ... other files like README.md, src/, ...
│           └── build/
│               ├── release/
│               ├── debug/
│               ├── dev_release/
│               ├── dev_debug/
│               ├── v0.7.2_release/
│               └── 2a4c6f3_release/
├── prebuilt/
│   ├── releases/
│   │   ├── v0.7.1/
│   │   ├── v0.7.2/
│   │   └── v0.7.3/
│   └── prereleases/
│       ├── latest_prerelease_20250702_1/
│       ├── ...
┊       ┊
.fi

If you ever get the error message 'Unexpected type '...'. Check the man-page.',
see if your '$XDG_DATA_HOME/c3vm/' directory matches the one above. There should
be no third directory at the 'git/prebuilt' level.

Git remotes are stored under 'git/remote/<user>_<repo>/'.
Builds (remote and local) are stored under 'build/<type>', where
<type> depends on branch, tag or commit, and ends with '_release' or '_debug'.
Builds on a branch can be updated when the branch updates.
Builds on tags or commits are fixed.


.SH EXIT CODES
.SS Starting checks
.B 1
\- Required directories missing and not able to create them
.br
.B 2
\- Required tools are missing
.br
.B 3
\- Unsupported OS (only GNU/Linux and macOS supported)

.SS Argument parsing failures
.B 10
\- Multiple subcommands found
.br
.B 11
\- Flag misses (correct) argument
.br
.B 12
\- Flag is used without its subcommand
.br
.B 13
\- Flag is used with wrong subcommand
.br
.B 14
\- Contradicting flags
.br
.B 15
\- Unknown argument/flag
.br
.B 16
\- Version is too low, c3vm only supports from v0.6.0 and upwards
.br
.B 17
\- Version did not match version-regex
.br

.SS Status failures
.B 20
\- Unknown type, should be 'git' or 'prebuilt'

.SS Install failures
.B 40
\- Directory not available to save into
.br
.B 41
\- Version was not recognized when determening the directory path
.br
.B 42
\- Download failed
.br
.B 43
\- Current c3c installation is not a symlink
.br
.B 44
\- Current c3c installation is not managed by c3vm
.br
.B 45
\- Failed to ensure OK git directory
.br
.B 46
\- Link to remote for existing git repo was not recognized as valid git-link-format
.br
.B 47
\- Failed to clone the git repository
.br
.B 48
\- Could not find CMakeLists.txt in the git repository
.br
.B 49
\- Failed to ensure OK build directory
.br
.B 50
\- Did not find 'origin' remote or its default branch
.br
.B 51
\- The passed rev is not recognized by git inside the git directory
.br
.B 52
\- Failed something while building (make or cmake error)
.br

.SS Enable failures
.B 60
\- Broken symlink in '$HOME/.local/bin/c3c'
.br
.B 61
\- Could not find specified version
.br
.B 62
\- Found multiple matching versions while expecting just one
.br

.SS Add-local failures
.B 70
\- Given path does not exist
.br
.B 71
\- Given name is invalid
.br

.SS Update failures
.B 80
\- Did not find the requested version to update
.br

.SS Remove failures
.B 90
\- Failed to execute the 'rm' command
.br
.B 91
\- Did not find the requested version to remove
.br

.SS Use failures
.B 100
\- Did not find the requested version to use
.br
.B 101
\- Did not find an executable 'c3c' for the requested version
.br
.B 102
\- Found multiple executable 'c3c's when expecting just one
.br