comrade package manager

This document is intended for developers of the comrade package manager.

This document explains the detailed mechanisms of the comrade package manager.

For information on how to contribute, please refer to the following Markdown: CONTRIBUTING.md
This document is structured as follows:
Chapter-2: How 'rade update' works
Chapter-3: How 'rade upgrade' works
Chapter-4: How 'rade install' works
Chapter-5: How 'rade list' works

If you can immediately understand what you want to do by looking at the source code, this document may not be necessary for you.

However, such individuals are rare. At least, I cannot do that.

This document exists for those who cannot understand even when looking at the source code.

Well, the introduction has been quite long, but let's move on to the next part. The next chapter is about how 'rade update' works.

rade update

rade update updates the package list for comrade.

The comrade package list is located in ~/.comrade/packagelist/.

When you execute update, comrade first deletes the packagelist and then clones the comrade package list. This ensures that the packagelist is completely up to date.

If ~/.comrade/packagelist/ is not found, it simply clones the packagelist and updates it to the latest version.

If the packagelist update fails

If comrade fails to clone the packagelist, it will output an error message and stop operation. Error message when cloning fails (This error message occurred due to lack of internet connection.)

Package contents

The contents of a package are as follows:

❯ tree hello_knife/
hello_knife/
├── capacity
├── dependencies
├── language
├── repository
└── version

1 directory, 5 files

(We used the hello_knife package as an example)

Let's look at each of these:

  • capacity This file indicates the capacity of the package. comrade checks this file during installation to display the capacity.

  • dependencies This file shows the package dependencies. During installation, it checks this file to confirm dependencies. (However, the current version of comrade doesn't have dependency resolution functionality...)

  • language This file contains the programming language used by the package. In the case of hello_knife, since it uses C language, the content of this file is C.

  • repository This file contains the repository URL of the package. During installation, comrade checks this file and clones the target repository.

  • version This file contains the version of the package. comrade checks and outputs this file during installation.

If you want to create a new package

There's an executable shell script called create_package.bash in rade-package-list. By executing this shell script, you can easily add a package.

Example (if the package to be added is "test-package"):

./create_package.bash test-package None rust https://github.com/test-package/rade-test-package 100 v1.0

Let's look at what each of these means:

  • test-package This is the package name. A package (directory) with this name will be generated.

  • None This represents dependencies. If there are no dependencies, you can use None or leave it blank.

  • rust This is the programming language used in this package. In this case, we assume test-package uses Rust, so 'rust' is written here. (Please use lowercase for language names)

  • https://github.com/test-package/rade-test-package This is the repository URL. This repository will be cloned and installed.

  • 100 This is the capacity used by the package program. We set it to 100 in this case. (Note that comrade's capacity notation is in bytes. So inputting 100 means the program is 100 bytes)

  • v1.0 This is the program version. This version will be output during installation. In this case, we set it as version 1.0.

This concludes this chapter. The next chapter will explain rade upgrade.

rade upgrade

We'll abbreviate comrade as rade.

rade upgrade keeps rade itself up to date. When you execute this, rade rebuilds itself and is reborn as a new rade. Let's take a look at what happens during the upgrade process.

Let's assume you've entered rade upgrade. Then, rade goes to check what its latest version is. If the latest version of rade is the same as the current version, rade does nothing and displays to the user, "rade is already up to date". What if the latest version of rade is higher than the current version? In that case, rade upgrades itself. Let's look at the upgrade process.

First, if a build directory exists, rade deletes it. Once the build directory is deleted or if it didn't exist, rade clones itself into the build directory. Next, rade updates the packagelist. This is to keep rade completely up to date during the upgrade. After the package list update is complete, rade uses make to build itself. This ensures that rade can work in any environment. When make finishes and everything completes normally, the upgrade is successfully finished. This is how rade achieves its upgrade.

This concludes this chapter. Next is the explanation of rade install.

rade install

The install function is an essential feature for a package manager. During installation, rade retrieves information about dependencies, capacity, language used, etc. Let's see what rade does when you enter rade install hello_knife.

Checking if the package exists

It checks if the package to be installed exists (in this case, checking if hello_knife exists). It checks all directories in the packagelist, and if a directory named hello_knife exists, it continues with the installation. If it doesn't exist, it outputs a message saying "No such package exists".

If it exists

If it exists, rade reads the following files in the package directory: dependencies file, language file, repository file, capacity file, and version file.

Then, rade reads the repository URL in the repository file and clones that repository.

If cloning is successful

When rade successfully clones, it searches for a directory named .comrade in that repository. If a .comrade directory exists, rade reads a file called exec_name inside the .comrade directory. This file contains the name of the executable file after compiling the repository. After reading this file, rade executes install.sh in that repository. If .comrade doesn't exist, rade assumes the executable file name is the repository name and executes install.sh. install.sh is a shell script that describes how to compile the repository and is essential for rade's program installation.

Compiling the program

rade executes install.sh for compilation. If install.sh terminates abnormally, rade stops execution and outputs an error message. There's one package where you can experience this abnormal termination. It's the build_error package. If you try to install the build_error package, it intentionally causes a compilation error, stops the build, and even stops rade. Feel free to try installing it if you're interested. (There's a rumor that something interesting happens if you fix it...) Back to the main topic.

When the build completes successfully, rade searches for the executable file. If the executable file exists, rade moves the program to ~/.comrade/bin/, writes logs, and successfully completes the installation. If the program doesn't exist, rade throws an error and terminates abnormally. (The process when the program doesn't exist is handled by .expect()) When the installation is complete, rade deletes the build directory and prepares for the next installation.

Here's the rade log when installing the hello_knife package:

❯ rade install hello_knife
>>> removing build directory... # Remove the build directory if it exists
>>> Clone package... # Since a package named hello_knife was found, read the repository file and clone it
install package: hello_knife
executable file name: hello # Since the .comrade directory existed, read and output exec_name in that directory
capacity: bytes # Read and output the capacity file. (Note: hello_knife's capacity file is empty, so it only displays bytes)
language: C # hello_knife is written in C language, so it displays C
versions: v1.0 # Output hello_knife's version
dependencies: None # hello_knife has no dependencies, so it displays None
repository: https://github.com/knife-package-manager/hello_knife # hello_knife's repository URL

install hello_knife?
[y/n] y
>>> Start Installation
>>> run install.sh (build start) # Execute install.sh and start the build
>>> build end # install.sh terminated normally
>>> moving file... # Move the executable file to ~/.comrade/bin/ to make it executable
>>> remove build directory... # Delete the build directory
>>> Fill in the log... # Write the installed items to the log
/home/inado/.comrade/log/install/hello_knife
All done! # Installation completed normally, notifying that everything is done
Installation is complete
For more information on hello_knife, please see https://github.com/knife-package-manager/hello_knife.

This concludes this chapter. Next is the explanation of the list function.

rade list

rade list outputs a list of packages that can be installed. Also, by adding the -i option to list, it displays the packages that are installed.

Example: rade list

❯ rade list
hello_knife
pravda
kajisp
noze
endolphine
build_error
stack-lang
scriptS

These are the list of packages that can currently be installed (as of September 2024).

rade list -i:

❯ rade list -i
pravda
rade
hello

These are the packages I have installed.

What's happening

What happens during rade list is that it reads the packagelist directory, and if a directory exists, it outputs the name of that directory.

When the -i option is executed, it simply reads the contents of ~/.comrade/bin/ and outputs its contents.

This concludes this chapter.

end

This concludes this document. It wasn't very long, but we greatly appreciate you reading it. If after reading this, you feel like you want to contribute to rade, we would be delighted if you could join our Discord server. Well then, let's meet again someday.

comrade package manager | discord server