target

_{^{This page applies to v0.1-alpha}}
home > 0.1-alpha home > 0.1-alpha reference home

Define a target

43 members:

• bindir
• cflags
• charset
• config
• configname
• cpplang
• debug
• define
• deps
• exceptions
• glob
• inc
• lflags
• libdir
• libs
• objdir
• pch
• pchsrc
• projdir
• projname
• projsuffix
• rtti
• rule
• shell
• src
• syslibs
• targetext
• targetname
• targetprefix
• targetsuffix
• type
• vc_extension_settings
• vc_extension_targets
• vcglobal
• vcguid
• vcimportlib
• vcnowarn
• vcprop
• vctoolset
• vcwarnlevel
• warnerror
• winsdkver
• write_src

bindir

Output directory for executables

K	V
variant	single
type	dir

Notes

• Does not check if path exists at generation time

Flags

K	V
:force	Suppress warning if path does not exist

cflags

Raw compiler command line switches

K	V
variant	array
elem type	string

Flags

K	V
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

charset

Character set

K	V
variant	single
type	choice
choices	:ascii, :mbcs, :unicode
default	:unicode

Examples

charset :unicode

config

Current target config as an id

K	V
variant	single
type	string

Notes

• Returns current config being processed. Use to define control flow to set config-specific atttributes
• Read only

configname

Display name of config as seen in IDE

K	V
variant	single
type	string

cpplang

C++ language standard

K	V
variant	single
type	choice
choices	C++11, C++14, C++17, C++20, C++23
default	"C++20"

debug

Flags config as a debug config

K	V
variant	single
type	bool

Notes

• Defaults to true if config id contains 'debug'

define

Preprocessor defines

K	V
variant	array
elem type	string

Flags

K	V
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

Examples

define "MYDEFINE"
define ["DEFINE1", "DEFINE2", "DEFINE3=1"]
define debug? ? "DEBUG" : "RELEASE"

deps

Target dependencies

K	V
variant	array
elem type	string

Notes

• List of ids of other cpp definitions. When a dependency is specified all the dependency's exports will be imported, the library will be linked to and a project level dependency created (unless :soft specified). To prevent linking specify :nolink - useful if only headers are required. A hard dependency is the default.This can be used for 'header only' dependencies
• Set on a per-target basis
• Unsorted

Flags

K	V
:nolink	TODO - TODO

Options

type

Dependency type

K	V
variant	single
type	choice
choices	:hard, :soft
default	:hard

Examples

      target :MyApp do
        type :app
        ...
        deps [:MyLib]
        deps [:MyLib2], type: :soft # No hard project dependency so not required in workspace
      end
      
      target :MyLib do
        type :lib
        ...
      end

      target :MyLib2 do
        type :lib
        inc ['.'], :export
        define ['MYLIB2'], :export
        ...
      end
    

exceptions

Enables C++ exceptions

K	V
variant	single
type	choice
choices	true, false, :structured
default	true

Examples

exceptions false # disable exceptions

glob

Glob for files

inc

Include paths

K	V
variant	array
elem type	dir

Notes

• Unsorted

Flags

K	V
:force	Suppress warning if path does not exist
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

Examples

inc ['mylibrary/include']
inc ['mylibrary/include'], :export # Export include path to dependents

lflags

Raw linker command line switches

K	V
variant	array
elem type	string

Flags

K	V
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

libdir

Output directory for libs

K	V
variant	single
type	dir

Notes

• Does not check if path exists at generation time

Flags

K	V
:force	Suppress warning if path does not exist

libs

Paths to required non-system libs

K	V
variant	array
elem type	file

Notes

• Unsorted

Flags

K	V
:force	Suppress warning if path does not exist
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

objdir

Output directory for object files

K	V
variant	single
type	dir

Notes

• Does not check if path exists at generation time
• Defaults to $(artefact_root)/$(arch)/obj/$(config)/$(projname)

Flags

K	V
:force	Suppress warning if path does not exist

pch

Precompiled header file

K	V
variant	single
type	rel_path

Notes

• In Visual Studio this must be the exact string inside the #include statement in each src file

pchsrc

Precompiled source file

K	V
variant	single
type	file

Flags

K	V
:force	Suppress warning if path does not exist

projdir

Directory in which projects will be generated

K	V
variant	single
type	dir
default	"."

Notes

• Set on a per-target basis
• Does not check if path exists at generation time

Flags

K	V
:force	Suppress warning if path does not exist

Examples

      target :MyApp do
        src ['**/*'] # Get all src in $(root), which defaults to directory of definition file
        projdir 'projects' # Place generated projects in 'projects' directory
      end
    

projname

Base name of project files

K	V
variant	single
type	basename

Notes

• Defaults to $(id)$(projsuffix)
• Set on a per-target basis

projsuffix

Optional suffix to be applied to $(projname)

K	V
variant	single
type	string

Notes

• Has no effect if $(projname) is set explicitly
• Set on a per-target basis

rtti

Enables runtime type information

K	V
variant	single
type	bool
default	false

Examples

rtti true

rule

TODO

K	V
variant	array
elem type	compound

Notes

• Unsorted

cmd

Command line to execute

K	V
variant	single
type	string

Notes

• Must be specified
• Use :absolute to make usage of $(input) or $(output) in the command line use absolute paths. Otherwise they will be relative to the generated project.

Flags

K	V
:absolute	TODO - TODO

implicit_input

Implicit input files

K	V
variant	single
type	file

Flags

K	V
:force	Suppress warning if path does not exist

input

TODO

K	V
variant	array
elem type	src

Flags

K	V
:force	Suppress warning if path does not exist

Options

vpath

Virtual path

K	V
variant	single
type	rel_path

Notes

• Controls IDE project layout

msg

Message

K	V
variant	single
type	string

Notes

• Message that will be echoed to console on execution of the rule.
• Certain characters like < > | & are automatically escaped to prevent unwanted side effects such as writing text to a file - this is a common reason why Visual Studio users are sometimes baffled as to why their custom build tool messages are not being printed.

output

Output files

K	V
variant	single
type	file

Notes

• Must be specified
• Does not check if path exists at generation time

Flags

K	V
:force	Suppress warning if path does not exist

Options

vpath

Virtual path

K	V
variant	single
type	rel_path

Notes

• Controls IDE project layout

properties

Per-file property

K	V
variant	hash
key type	string
value type	to_s

Notes

• In the form 'src <file>, properties: {name: :value}'

shell

Shell commands to execute during build

K	V
variant	array
elem type	string

Notes

• Maps to build events in Visual Studio

Flags

K	V
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

Options

when

When shell command should be run

K	V
variant	single
type	choice
choices	:PreBuild, :PreLink, :PostBuild

Notes

• Must be specified

src

Specify source files

K	V
variant	array
elem type	src

Notes

• Unsorted

Flags

K	V
:force	Suppress warning if path does not exist
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

Options

vpath

Virtual path

K	V
variant	single
type	rel_path

Notes

• Controls IDE project layout

properties

Per-file property

K	V
variant	hash
key type	string
value type	to_s

Notes

• In the form 'src <file>, properties: {name: :value}'

Examples

      # Add all src in $(root) whose extension is in $(src_ext)
      src ['*']

      # Add all src in $(root)/src whose extension is in $(src_ext), recursively
      src ['src/**/*']

      # Glob matches are not required to add whole directory recursively (whose extension is in $(src_ext))
      src ['src']

      # Add all src recursively but excluding test files
      src ['src'], exclude: ['test/**/*']

      # Add src explicitly
      src ['main.c', 'io.c']

      # Array brackets not required for one item
      src 'main.c'

      # Add src explicitly even if extension not in $(src_ext)
      src ['build.jaba']

      # Add src by glob match even if extension not in $(src_ext) only if has explicit extension
      src ['*.jaba']

      # Force addition of file not on disk
      src ['does_not_exist.cpp'], :force

      # Precede with ./ to force path to be relative to current jaba file even if $(root) points elsewhere.
      # Useful if you want to make $(root) point to a 3rd party distro but you want to add a local file
      src ['./local.cxx']

      # Add src in bulk without needing quotes, commas or square brackets. Options can be added as normal.
      src %w(main.c dmydln.c miniinit.c array.c ast.c bignum.c class.c compar.c compile.c)
      src %w(
        main.c dmydln.c miniinit.c array.c
        ast.c bignum.c class.c compar.c compile.c
      )

      # Place matching files in a specific folder location within the project file
      src '*_win.cpp', vpath: 'win32'

      # Set a per-file property or properties
      src 'main.cpp', properties: {MyPropertyName1: :MyPropertyValue1, MyPropertyName2: :MyPropertyValue2}
    

syslibs

System libs

K	V
variant	array
elem type	string

Notes

• Unsorted

Flags

K	V
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

targetext

Extension to apply to $(targetname)

K	V
variant	single
type	ext

Notes

• Defaults to standard extension for $(type) of project for target $(platform)

targetname

Basename of output file without extension

K	V
variant	single
type	basename

Notes

• Defaults to $(targetprefix)$(projname)$(targetsuffix)

targetprefix

Prefix to apply to $(targetname)

K	V
variant	single
type	string

Notes

• Has no effect if $(targetname) specified

targetsuffix

Suffix to apply to $(targetname)

K	V
variant	single
type	string

Notes

• Has no effect if $(targetname) specified

type

Target type

K	V
variant	single
type	choice
choices	:app, :console, :lib, :dll
default	:console

vc_extension_settings

Path to a .props file

K	V
variant	hash
key type	ext
value type	file

Notes

• Set on a per-target basis

Flags

K	V
:force	Suppress warning if path does not exist

vc_extension_targets

Path to a .targets file

K	V
variant	hash
key type	ext
value type	file

Notes

• Set on a per-target basis

Flags

K	V
:force	Suppress warning if path does not exist

vcglobal

Address Globals property group in a vcxproj directly

K	V
variant	hash
key type	string
value type	to_s

Notes

• Set on a per-target basis

Flags

K	V
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

Options

condition

Condition

K	V
variant	single
type	string

vcguid

Globally unique id (GUID)

K	V
variant	single
type	uuid

Notes

• Seeded by $(projname). Required by Visual Studio project files
• Set on a per-target basis

vcimportlib

Name of import lib for use will dlls

K	V
variant	single
type	file

Notes

• Does not check if path exists at generation time
• Defaults to $(projname)$(targetsuffix).lib

Flags

K	V
:force	Suppress warning if path does not exist

vcnowarn

Warnings to disable

K	V
variant	array
elem type	int

Flags

K	V
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

Examples

vcnowarn [4100, 4127, 4244]

vcprop

Address per-configuration sections of a vcxproj directly

K	V
variant	hash
key type	string
value type	to_s

Flags

K	V
:export	Export specified elements to dependent targets - Set on source target and on dependent target
:export_only	Export specified elements to dependent targets - Only set on the dependent target

Options

condition

Condition string

K	V
variant	single
type	string

Examples

      # Insert property into first PropertyGroup section (the one that contains ConfigurationType)
      vcprop 'PG1|MyProperty', 'MyValue'

      # Insert property into second PropertyGroup section
      vcprop 'PG2|MyProperty2', 10

      # Insert boolean property into ClCompile section
      vcprop 'ClCompile|BufferSecurityCheck', false

      # Can use a symbol for property value. Same result as using quoted string.
      vcprop 'Link|EntryPointSymbol', :mainCRTStartup

      vcprop 'Midl|SuppressStartupBanner, true
    

vctoolset

Toolset version to use

K	V
variant	single
type	choice
choices	$(DefaultPlatformToolset), v100, v110, v120, v140, v141, v142, v143
default	"$(DefaultPlatformToolset)"

Notes

• Defaults to default platform toolset for version of Visual Studio in use

vcwarnlevel

Visual Studio warning level

K	V
variant	single
type	choice
choices	1, 2, 3, 4
default	3

warnerror

Enable warnings as errors

K	V
variant	single
type	bool
default	false

Examples

warnerror true

winsdkver

Windows SDK version

K	V
variant	single
type	choice
choices	10.0.16299.0, 10.0.17134.0, 10.0.17763.0, 10.0.18362.0, nil
default	nil

Notes

• Set on a per-target basis Examples

winsdkver '10.0.18362.0'
# wrapper for
vcglobal :WindowsTargetPlatformVersion, winsdkver

write_src

Creates a src and adds to build

K	V
variant	array
elem type	compound

Notes

• Unsorted

fn

Filename

K	V
variant	single
type	file

Notes

• Does not check if path exists at generation time

Flags

K	V
:force	Suppress warning if path does not exist

Options

properties

Per-file property

K	V
variant	hash
key type	string
value type	to_s

Notes

• In the form 'src <file>, properties: {name: :value}'

vpath

Virtual path

K	V
variant	single
type	rel_path

Notes

• Controls IDE project layout

line

Line to add to file

K	V
variant	array
elem type	to_s

_{^{Generated using Redcarpet, CodeRay, Inter and FiraCode. css by Harry Denholm.}}