README.md

ComputerCraft Updater

Lightweight dependency manager for CC: Tweaked.

The goal is to make an easier way to distribute code to multiple computers quickly and consistently. This is not designed to be a full-blown package manager (maybe someday), but it does allow you to update modules from Github as well as automatically pull dependencies for them (no conflict resolution).

Why "Another Package Manager"

There are so many package managers for ComputerCraft that no one uses them. You do not need to use this one, I made it for me and if I am the only one that uses, that is fine.

But why I think you should use this:

• 100% open source, fork it, copy it, do whatever you want with it.
• No external backends. It is completely built on top of Github and Github Actions so no servers with code you cannot see.
  • (NOTE: I only ever use Github, if you want another source code site backend such as GitLab, make an issue/PR and we can chat!)
• Completely built on top of Git so there is versioning, version pinning, etc.
• Small! Only 5.82KB when fully minified (~3 files)
• Automatic minification of Lua files so you can have readable source files but still download compact files for your computers
• Easy to integrate, just copy and tweak the workflows and scripts from the template repo and you should be good to go!

Install

Run the following command in your computer:

wget run https://raw.githubusercontent.com/AngellusMortis/cc-updater/master/install.lua

Since ComputerCraft computers have size limits for computers, by default, all Lua files that are downloaded are minified. If you would like to change this behavior global for all files, you can run

ghuconf set minified false

Adding Repos

You can add a repo for your computer using the ghuconf command. Format for adding new repos is ghuconf add extraRepos {username}/{repo}:/src.

For example, if you want to add my rendering library:

ghuconf add extraRepos AngellusMortis/cc-render@v1 default

You can optionally add @{ref} after the repo to pull a specific git ref (branch, tag or sha).

You can find Github repos using cc-updater at by searching Github

The last parameter is how you want to handle minification. default uses the global ghu.minified setting, true forces files to be minified and false forces them to not be minified.

Making New Repos

Go to the template repo and click "Use this template" and create a public repository (private repos are not supported). After you create your repo, go to "Settings -> Actions -> General" and change "Workflow Permissions" to "Read and write permissions"

Add your files the src directory and commit/push them. Github Actions will automatically generate a src/manifest.json whenever you commit to the default branch. After the manifest.json is made, you can use ghuconf to add the repo to your computer.

The folder structure largely mimics the folder structure from the CraftOS rom folder:

• /help: .txt files added to the /help folder will be automatically added as help modules

• /programs: .lua files added to the /programs folder will automatically be available in your shell path to run. Matches the same folder structure as CraftOS rom folder (/programs/turtle will be added if it is a turtle, etc.)

• /autorun: Since cc-updater adds a startup.lua to your computer, you can add .lua files to /autorun that will automatically be ran to extend startup.lua and automatically start programs. This functionallity can be disabled with ghuconf set autoRun false.

• /apis: .lua files added to the /apis folder will be available to import as Lua modules. Since there is no persistent way to add module paths, you will have to add the following to a Lua file to load them by their relative name:

      -- ComputerCraft does not have a way to persist module loaders
      -- So importing the core updater library will automatically initialize the module loaders if needed
      require(settings.get("ghu.base") .. "core/apis/ghu")
  
      -- example to load UI library from WIP rendering lib above (AngellusMortis/cc-render):
      local ui = require("am.ui")

• /deps.json: A JSON array of other Github repos that this one depends on. Will automatically be injected into the manifest.json when it is generated.

Versioning

There are a couple of Github Actions workflows to help you manage Git tags and versions in the template repo. It is designed to follow a 2 digit semver. In other words, you can run the "Bump Minor" workflow to increase the minor version, indicating that the changes are safe and there are no breaking API changes and anyone using that major version tag will automatically get the update next time they run ghuupdate. Then there is the "Bump Major" workflow to cut a new major version which people will not automatically get unless they are using master as a ref.

The initial version of the template repo is 0.1.

Installing

The template repo provides an install script example. To make it functional, all you need to do is fill in the installRepo variable at the top of the script then you can wget run {url} the script and it will install your repo and cc-updater for you (users do not need to manually install cc-updater to use your project).

Provided Programs

ghuupdate

This is basically the secret sauce. ghuupdate will use the settings ghu.coreRepo and ghu.extraRepos to pull manifest.json files from those Github repos and then update the files on disk. ghuupdate is automatically ran in the startup.lua. To disable the auto update, you can run ghuconf set autoUpdate false

ghureload

Simple script to clear shell paths and then re-run the default startup.lua to "simulate" a reboot. Really useful if you cannot easily reboot the computer (background program running or you are using something like the awesome ComputerCraft VS Code extension.

ghuconf

Helper program to manage cc-updater settings. You can do the same thing with set and get programs, but this one is just a bit nicer since it is specific for ghu. settings.

All Settings

• base - the root folder for cc-updater. Changing the value is not supported/tested
• autoUpdate - Automatically run ghuupdate in startup.lua. Defaults to true
• autoRun - Automatically run any .lua files in /autoruns for each cc-updater repo. Defaults to true
• coreRepo - The Github ref for the cc-updater repo. Changing the value is not supported/tested
• extraRepos - A list of subscribed Github repos
• minified - Downloads files minified or not. Defaults to true

Examples

• ghuconf list will list all ghu. settings
• ghuconf get extraRepo will list all subscribed Github repos
• ghuconf help autoUpdate will print out the help for the ghu.autoUpdate setting
• ghuconf set autoRun false will disable automatically running /autoruns
• ghuconf set autoUpdate default will revert auto update to the default value (true)
• ghuconf add extraRepos example/test:/src default will subscribe to Github repo "example/test" with the path "/src" with default minified Lua setting (use global)
• ghuconf add extraRepos example/test:/src false will subscribe to Github repo "example/test" with the path "/src" without minified Lua files
• ghuconf remove extraRepos example/test:/src will unsubscribe to Github repo "example/test" (does not delete files)

Note About Caching

CraftOS seems heavily cache files http calls. As a result, it may take up to 5 minutes for new files to be detected by ghuupdate.lua. If you know any way to improve this, please make an issue or PR and let's talk about it!