README
¶
utils
Shared utilities for console output, file operations, downloads, and script parsing.
Architecture
console.go Styled console output, logging, user prompts
download.go HTTP downloads with progress bars
files.go File and directory utilities
parser.go Build script metadata parsing
Console Output
Print: PrintMessage, PrintSuccess, PrintWarning, PrintError, PrintHint, PrintNote, PrintDebug
Style: StyleName (yellow), StylePath, StyleAction, StyleCommand, StyleHint (cyan), StyleError (red), StyleSuccess (green), StyleWarning (yellow)
Modes: DebugMode, QuietMode, YesMode
utils.PrintMessage("Installing %s", utils.StyleName("package"))
utils.PrintSuccess("Build completed")
utils.ShouldAnswerYes() // true when YesMode or non-interactive
utils.ReadLineContext(ctx context.Context) // read line with cancellation
File Operations
Checks: FileExists, DirExists, IsImg, IsSqf, IsSif, IsOverlay
Operations: EnsureDir
Permissions: PermFile (0664), PermDir (0775), PermExec (0775)
Permission Fixers: FixPermissionsDefault(path), ShareToUGORecursive(path)
Downloads
utils.DownloadFile(url, destPath) // with progress bar
utils.DownloadExecutable(url, destPath) // sets exec permissions
Script Parsing
// parseModuleLoad: also extract "module load" / "ml" lines as deps
deps, err := utils.GetDependenciesFromScript(scriptPath, parseModuleLoad)
prompts, err := utils.GetInteractivePromptsFromScript(scriptPath)
// extract scheduler directives and apply defaults (scheduler package)
specs, err := scheduler.ReadScriptSpecsFromPath(scriptPath)
Documentation
¶
Index ¶
- Constants
- Variables
- func CreateFileWritable(path string) (*os.File, error)
- func DirExists(path string) bool
- func DownloadExecutable(url, destPath string) error
- func DownloadFile(url, destPath string) error
- func EnsureDir(path string) error
- func EnsureTmpSubdir(dir string) error
- func FileExists(path string) bool
- func FixPermissions(path string, filePerm, dirPerm os.FileMode) error
- func FixPermissionsDefault(path string) error
- func FormatBytes(bytes int64) string
- func FormatDuration(d time.Duration) string
- func FormatMemoryMB(mb int64) string
- func GetDependenciesFromScript(scriptPath string, parseModuleLoad bool) ([]string, error)
- func GetExternalBuildTypeFromScript(scriptPath string) (string, error)
- func GetInteractivePromptsFromScript(scriptPath string) ([]string, error)
- func GetTmpDir() string
- func GetWhatIsFromScript(scriptPath string) string
- func IsApptainerImage(path string) bool
- func IsImg(path string) bool
- func IsInteractiveShell() bool
- func IsOverlay(path string) bool
- func IsSif(path string) bool
- func IsSqf(path string) bool
- func IsWritableDir(dir string) bool
- func IsYaml(path string) bool
- func NormalizeNameVersion(nameVersion string) string
- func ParseDHMSTime(timeStr string) (time.Duration, error)
- func ParseHMSTime(timeStr string) (time.Duration, error)
- func ParseMemoryMB(memStr string) (int64, error)
- func ParseMemoryMBWithDefault(memStr, defaultUnit string) (int64, error)
- func ParseSizeToMB(sizeStr string) (int, error)
- func ParseWalltime(timeStr string) (time.Duration, error)
- func PrintDebug(format string, a ...interface{})
- func PrintError(format string, a ...interface{})
- func PrintHint(format string, a ...interface{})
- func PrintMessage(format string, a ...interface{})
- func PrintNote(format string, a ...interface{})
- func PrintSuccess(format string, a ...interface{})
- func PrintWarning(format string, a ...interface{})
- func ReadGzipJSONFile(path string, out any) error
- func ReadLineContext(ctx context.Context) (string, error)
- func RemoveDirIfEmpty(dir string)
- func ShareToUGORecursive(path string) error
- func ShouldAnswerYes() bool
- func StripInlineComment(s string) string
- func StyleAction(act string) string
- func StyleCommand(cmd string) string
- func StyleDebug(msg string) string
- func StyleError(msg string) string
- func StyleHighlight(text string) string
- func StyleHint(msg string) string
- func StyleInfo(msg string) string
- func StyleName(name string) string
- func StyleNote(msg string) string
- func StyleNumber(num interface{}) string
- func StylePath(path string) string
- func StyleSuccess(msg string) string
- func StyleTitle(title string) string
- func StyleWarning(msg string) string
- func URLExists(url string) bool
- func WriteGzipJSONFileAtomic(path string, value any) error
Constants ¶
const PermDir os.FileMode = 0775
Dir: u=rwx, g=rwx, o=rx (Requires +x to traverse)
const PermExec os.FileMode = 0775
Exec: u=rwx, g=rwx, o=rx (Executable files with group write access)
const PermFile os.FileMode = 0664
Standard default permissions File: u=rw, g=rw, o=r
Variables ¶
var DebugMode = false
DebugMode controls whether PrintDebug output is visible.
var QuietMode = false
QuietMode controls whether verbose messages are suppressed (errors/warnings still shown)
var YesMode = false
YesMode controls whether to automatically answer yes to all prompts
Functions ¶
func CreateFileWritable ¶ added in v1.3.0
CreateFileWritable creates or truncates a file using standard writable file permissions.
func DownloadExecutable ¶
DownloadExecutable downloads a file and sets it as executable (PermExec).
func DownloadFile ¶
DownloadFile downloads a file from url to destPath.
func EnsureTmpSubdir ¶ added in v1.3.0
EnsureTmpSubdir creates the leaf directory dir with permissions based on the parent:
- Parent world-writable (o+w, e.g. /tmp with mode 1777): use 0700 so other users on the same node cannot read or list the contents.
- Parent private (scheduler job dir, user-controlled path): use PermDir (0775).
Only the leaf is created; the parent must already exist. An already-existing directory is accepted silently (safe for concurrent builds).
func FileExists ¶
FileExists checks if a file exists and is not a directory.
func FixPermissions ¶
FixPermissions automatically adjusts permissions for a path using the provided modes. If 'path' is a file, it sets it to 'filePerm'. If 'path' is a directory, it recursively sets files to 'filePerm' and subdirs to 'dirPerm'.
func FixPermissionsDefault ¶
FixPermissionsDefault is a helper that applies standard permissions (0664/0775). It is a shorthand for FixPermissions(path, PermFile, PermDir).
func FormatBytes ¶
FormatBytes formats bytes into human-readable format (e.g., "1.50 GB").
func FormatDuration ¶ added in v1.3.0
FormatDuration formats a duration dropping zero trailing components. Examples: 2h0m0s → "2h", 48h → "2d", 25h30m → "1d1h30m", 1h30m15s → "1h30m15s".
func FormatMemoryMB ¶ added in v1.3.0
FormatMemoryMB formats a MB value into a human-readable string. Uses "GB" when divisible by 1024, otherwise "MB". Examples: 8192 → "8GB", 1536 → "1536MB".
func GetDependenciesFromScript ¶
GetDependenciesFromScript parses a build script and extracts dependencies from #DEP: comments and, optionally, module load / ml commands. Set parseModuleLoad=true to also parse "module load" and "ml" lines. Returns a list of normalized dependency names with duplicates removed.
func GetExternalBuildTypeFromScript ¶ added in v1.3.0
GetExternalBuildTypeFromScript parses external build script TYPE metadata. Supported tag forms:
- #TYPE:<value>
- TYPE:<value>
If TYPE is not present, it defaults to "app". Supported values (case-insensitive):
- app aliases: app, env, tool, conda, small
- data aliases: data, ref, large
func GetInteractivePromptsFromScript ¶
GetInteractivePromptsFromScript parses a build script and extracts interactive prompt lines beginning with "#INTERACTIVE:". Returns a list of prompt strings (without the prefix) or an error if the file cannot be read.
func GetTmpDir ¶ added in v1.3.0
func GetTmpDir() string
GetTmpDir returns the best available tmp directory for condatainer builds. Priority:
- CNT_TMPDIR (explicit override)
- Scheduler-specific local node storage: SLURM_TMPDIR, PBS_TMPDIR, LSF_TMPDIR, _CONDOR_SCRATCH_DIR
- Common tmp env vars: TMPDIR, TEMP, TMP
- /tmp (always available)
Always appends cnt-$USER to avoid collisions between users.
func GetWhatIsFromScript ¶ added in v1.2.0
GetWhatIsFromScript reads a script and extracts the first #WHATIS: line. Returns the trimmed description string, or empty string if not found.
func IsApptainerImage ¶
IsApptainerImage checks if the file matches any supported Apptainer image format. Returns true for .sif, .img, .sqf, .sqsh, .squashfs.
func IsImg ¶
IsImg checks if the path has an ext3 overlay extension (.img). Note: In Apptainer context, .img usually implies a writable ext3 overlay.
func IsInteractiveShell ¶
func IsInteractiveShell() bool
IsInteractiveShell checks if stdout is connected to a TTY (interactive terminal). Returns true if the program is running in an interactive shell, false otherwise.
func IsOverlay ¶
IsOverlay checks if the path is an overlay file (.img, .sqf, .sqsh, .squashfs). This is used for CondaTainer overlay detection.
func IsSif ¶
IsSif checks if the path has a Singularity Image Format extension (.sif). This is the native format for Apptainer/Singularity.
func IsSqf ¶
IsSqf checks if the path has a SquashFS extension (.sqf, .sqsh, .squashfs). These are read-only compressed images.
func IsWritableDir ¶ added in v1.3.0
IsWritableDir checks whether dir is writable by creating a small probe file. It creates the directory if needed and enforces standard directory/file permissions.
func IsYaml ¶
IsYaml checks if the path has a YAML extension (.yaml, .yml). Useful for Conda environment definition files.
func NormalizeNameVersion ¶
NormalizeNameVersion normalizes package spec formats so that "name/version", "name=version", "name@version" are treated the same. Converts = and @ to /, and -- to /, then strips whitespace.
func ParseDHMSTime ¶ added in v1.2.0
ParseDHMSTime handles colon-separated and D-HH:MM:SS walltime formats.
func ParseHMSTime ¶ added in v1.2.0
ParseHMSTime parses colon-separated walltime "HH:MM:SS", "HH:MM", or "MM" (bare minutes).
func ParseMemoryMB ¶ added in v1.2.0
ParseMemoryMB parses memory strings like "8G", "1024M", "512K", "1T" into MB (int64). Default unit is MB when no suffix is given.
func ParseMemoryMBWithDefault ¶ added in v1.3.0
ParseMemoryMBWithDefault parses a memory string into MB. When the string has an explicit unit suffix (G/GB/M/MB/K/KB/T/TB) it is used directly. For bare numbers the provided defaultUnit is applied (e.g. "KB", "MB", "GB").
func ParseSizeToMB ¶
ParseSizeToMB converts strings like "10G", "500M", "1024" into Megabytes (int). Default unit is MB if no suffix is provided. Delegates to ParseMemoryMB.
func ParseWalltime ¶ added in v1.2.0
ParseWalltime parses a walltime string into a duration. Supported formats:
Compound (Go-style, with int day): 4d12h, 2h30m, 3h, 90m, 1d2h30m45s, 1.5h
Colon-separated: D-HH:MM:SS, HH:MM:SS, HH:MM, MM
func PrintDebug ¶
func PrintDebug(format string, a ...interface{})
PrintDebug prints a debug message with a Gray tag (only if DebugMode is true). → stderr Output: [CNT][DBG] Executing: rm -rf /tmp/foo
func PrintError ¶
func PrintError(format string, a ...interface{})
PrintError prints an error message with a Red tag. → stderr Output: [CNT][ERR] Something failed.
func PrintHint ¶
func PrintHint(format string, a ...interface{})
PrintHint prints a helpful hint with a Cyan tag. → stderr Output: [CNT][HINT] Try running with --force.
func PrintMessage ¶
func PrintMessage(format string, a ...interface{})
PrintMessage prints a standard info message. → stderr Output: [CNT] Message...
func PrintNote ¶
func PrintNote(format string, a ...interface{})
PrintNote prints a note with a Magenta tag. → stderr Output: [CNT][NOTE] This might take a while.
func PrintSuccess ¶
func PrintSuccess(format string, a ...interface{})
PrintSuccess prints a success message with a Green tag. → stderr Output: [CNT][PASS] Operation complete.
func PrintWarning ¶
func PrintWarning(format string, a ...interface{})
PrintWarning prints a warning with a Yellow tag. → stderr Output: [CNT][WARN] Disk is almost full.
func ReadGzipJSONFile ¶ added in v1.3.0
ReadGzipJSONFile opens a .json.gz file and decodes JSON into out.
func ReadLineContext ¶ added in v1.2.0
ReadLineContext reads a trimmed line from stdin, preserving case. Returns context.Canceled if ctx is done before input arrives.
func RemoveDirIfEmpty ¶ added in v1.3.0
func RemoveDirIfEmpty(dir string)
RemoveDirIfEmpty removes dir if it exists and contains no files or subdirectories. Silently does nothing if dir is not empty or does not exist.
func ShareToUGORecursive ¶
ShareToUGORecursive recursively sets permissions to share files with user, group, and others. Files: ug+rw,o+r (0664) Directories: ug+rwx,o+rx (0775) This matches the Python implementation's share_to_ugo_recursive function.
func ShouldAnswerYes ¶
func ShouldAnswerYes() bool
ShouldAnswerYes checks if we should automatically answer yes to prompts Returns true if --yes flag is set, false otherwise
func StripInlineComment ¶ added in v1.2.0
StripInlineComment removes everything after the first '#' character (inline comment). Returns the trimmed string without the comment.
func StyleAction ¶
StyleAction formats verbs or active operations (Yellow).
func StyleCommand ¶
StyleCommand formats shell commands or flags (Gray/Faint).
func StyleDebug ¶
StyleDebug formats low-level technical info (Gray).
func StyleError ¶
StyleError formats critical failure messages (Red).
func StyleHighlight ¶
StyleHighlight formats search matches or highlighted text (Yellow Bold).
func StyleNumber ¶
func StyleNumber(num interface{}) string
StyleNumber formats counts, sizes, or IDs (Magenta).
func StyleSuccess ¶
StyleSuccess formats success messages (Green).
func StyleWarning ¶
StyleWarning formats non-critical warnings (Yellow).
func WriteGzipJSONFileAtomic ¶ added in v1.3.0
WriteGzipJSONFileAtomic encodes value as JSON, writes it as .json.gz to a temp file, then atomically renames it to path.
Types ¶
This section is empty.
Source Files