Herolib

Herolib is an opinionated library primarily used by ThreeFold to automate cloud environments. It provides a comprehensive set of tools and utilities for cloud automation, git operations, documentation building, and more.

Complete Documentation

Installation

For Users

The Hero tool can be installed with a single command:

curl https://raw.githubusercontent.com/incubaid/herolib/refs/heads/development/scripts/install_hero.sh | bash

Hero will be installed in:

• /usr/local/bin for Linux
• ~/hero/bin for macOS

After installation on macOS, you may need to do source see below or restart your terminal to ensure the hero command is available:

source ~/.zprofile

The Hero tool can be used to work with git, build documentation, interact with Hero AI, and more.

For Developers

For development purposes, use the automated installation script:

curl 'https://raw.githubusercontent.com/incubaid/herolib/refs/heads/development/scripts/install_v.sh' > /tmp/install_v.sh
bash /tmp/install_v.sh --analyzer --herolib 

#do not forget to do the following this makes sure vtest and vrun exists
cd ~/code/github/incubaid/herolib/scripts
v install_herolib.vsh

# IMPORTANT: Start a new shell after installation for paths to be set correctly

Installation Options

V & HeroLib Installer Script

Usage: ~/code/github/incubaid/herolib/scripts/install_v.sh [options]

Options:
  -h, --help     Show this help message
  --reset        Force reinstallation of V
  --remove       Remove V installation and exit
  --analyzer     Install/update v-analyzer
  --herolib      Install our herolib

Examples:
  ~/code/github/incubaid/herolib/scripts/install_v.sh
  ~/code/github/incubaid/herolib/scripts/install_v.sh --reset
  ~/code/github/incubaid/herolib/scripts/install_v.sh --remove
  ~/code/github/incubaid/herolib/scripts/install_v.sh --analyzer
  ~/code/github/incubaid/herolib/scripts/install_v.sh --herolib
  ~/code/github/incubaid/herolib/scripts/install_v.sh --reset --analyzer # Fresh install of both

Features

Herolib provides a wide range of functionality:

• Cloud automation tools

• Git operations and management

  Offline Mode for Git Operations

  Herolib now supports an offline mode for Git operations, which prevents automatic fetching from remote repositories. This can be useful in environments with limited or no internet connectivity, or when you want to avoid network calls during development or testing.

  To enable offline mode:

  • Via GitStructureConfig: Set the offline field to true in the GitStructureConfig struct.
  • Via GitStructureArgsNew: When creating a new GitStructure instance using gittools.new(), set the offline parameter to true.
  • Via Environment Variable: Set the OFFLINE environment variable to any value (e.g., export OFFLINE=true).

  When offline mode is active, git fetch --all operations will be skipped, and a debug message "fetch skipped (offline)" will be printed.

• Documentation building

• Hero AI integration

• System management utilities

• And much more

Check the cookbook for examples and use cases.

Testing

Running tests is an essential part of development. To run the basic tests:

# Run all basic tests
~/code/github/incubaid/herolib/test_basic.vsh

# Run tests for a specific module
vtest ~/code/github/incubaid/herolib/lib/osal/package_test.v

# Run tests for an entire directory
vtest ~/code/github/incubaid/herolib/lib/osal

The vtest command is an alias for testing functionality.

Contributing

We welcome contributions to Herolib! Please see our CONTRIBUTING.md file for detailed information on:

• Setting up your development environment
• Understanding the repository structure
• Following our development workflow
• Making pull requests
• CI/CD processes

Troubleshooting

TCC Compiler Error on macOS

If you encounter the following error when using TCC compiler on macOS:

In file included from /Users/timurgordon/code/github/vlang/v/thirdparty/cJSON/cJSON.c:42:
/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/math.h:614: error: ';' expected (got "__fabsf16")

This is caused by incompatibility between TCC and the half precision math functions in the macOS SDK. To fix this issue:

1. Open the math.h file:

   sudo nano /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/math.h
   

2. Comment out the following lines (around line 612-626):

   /* half precision math functions */
   // extern _Float16 __fabsf16(_Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __hypotf16(_Float16, _Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __sqrtf16(_Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __ceilf16(_Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __floorf16(_Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __rintf16(_Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __roundf16(_Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __truncf16(_Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __copysignf16(_Float16, _Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __nextafterf16(_Float16, _Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __fmaxf16(_Float16, _Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __fminf16(_Float16, _Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   // extern _Float16 __fmaf16(_Float16, _Float16, _Float16) __API_AVAILABLE(macos(15.0), ios(18.0), watchos(11.0), tvos(18.0));
   

3. Save the file and try compiling again.

Additional Resources

• Complete Documentation
• Cookbook Examples
• AI Prompts

Generating Documentation

To generate documentation locally:

cd ~/code/github/incubaid/herolib
bash doc.sh