build #

Description

build provides a small build system leveraging V(SH) for the buildscript.

Example

See also: build_system example

#!/usr/bin/env -S v run

import build
// .vsh automatically imports `os`, so you don't need this typically
import os { system }

const app_name = 'vlang'
const program_args = 'World'

mut context := build.context(
    // Set the default task to `release` when no arguments are provided
    default: 'release'
)

context.task(name: 'doc', run: |self| system('v doc .'))
context.task(name: 'run', run: |self| system('v run . ${program_args}'))
context.task(name: 'build', run: |self| system('v .'))
context.task(name: 'build.prod', run: |self| system('v -prod .'))

context.task(
    name:    'release'
    depends: ['doc']
    run:     fn (self build.Task) ! {
        system('v -prod -o build/${app_name} .')
        // You could use Git to publish a release here too
    }
)

context.run()

Pre-Compiling

Running VSH scripts requires V to compile the script before executing it, which can cause a delay between when you run ./build.vsh and when the script actually starts executing.

If you want to fix this, you can "pre-compile" the buildscript by building the script, i.e, running v -skip-running build.vsh.

You will need to rebuild every time you change the buildscript, and you should also add /build > to your .gitignore

If you want maximum speed, you can also v -prod -skip-running build.vsh

fn context(params BuildContextParams) BuildContext

context creates an empty BuildContext.

struct ArtifactParams {
pub:
	name       string @[required]
	help       string
	depends    []string
	should_run fn (Task) !bool = |self| !os.exists(self.name)
	run        fn (Task) ! @[required]
	// repeatable controls whether or not this task can run multiple times per build cycle
	repeatable bool
}

struct BuildContext {
mut:
	// should_run caches the result of should_run from tasks.
	should_run map[string]bool
	tasks      []Task
pub mut:
	// default is the default task to run when no others are provided.
	default ?string
}

fn (mut context BuildContext) task(config TaskParams)

task creates a task for the given context.

fn (mut context BuildContext) artifact(config ArtifactParams)

artifact creates an artifact task for the given context.

fn (mut context BuildContext) get_task(name string) ?&Task

get_task gets the task with the given name.

fn (mut context BuildContext) exec(name string)

exec executes the task with the given name in the context.

fn (mut context BuildContext) run()

run executes all tasks provided through os.args.

struct BuildContextParams {
pub:
	default ?string
}

struct Task {
	run        fn (Task) !     @[required]
	should_run fn (Task) !bool @[required]
	// repeatable controls whether or not this task can run multiple times per build cycle
	repeatable bool
pub:
	name    string
	help    string
	depends []string
mut:
	did_run bool
}

fn (mut task Task) exec(mut context BuildContext)

exec runs the given task and its dependencies

struct TaskParams {
pub:
	name       string @[required]
	help       string
	depends    []string
	should_run fn (Task) !bool = |self| true
	run        fn (Task) ! @[required]
	// repeatable controls whether or not this task can run multiple times per build cycle
	repeatable bool
}