diff options
Diffstat (limited to 'doc/manual.asciidoc')
| -rw-r--r-- | doc/manual.asciidoc | 75 |
1 files changed, 46 insertions, 29 deletions
diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc index 43b8fa1..39c197e 100644 --- a/doc/manual.asciidoc +++ b/doc/manual.asciidoc @@ -416,11 +416,51 @@ A file is a series of declarations. A declaration can be one of: +include _path_+. The difference between these is explained below <<ref_scope,in the discussion about scoping>>. +Lexical syntax +~~~~~~~~~~~~~~ + Comments begin with `#` and extend to the end of the line. -Newlines are significant, but they can be escaped by putting a `$` -before them. To produce a literal `$` in a path or variable value use -`$$`. +Newlines are significant. Statements like `build foo bar` are a set +of space-separated tokens that end at the newline. Newlines and +spaces within a token must be escaped. + +There is only one escape character, `$`, and it has the following +behaviors: + +[horizontal] +`$` followed by a newline:: escape the newline (continue the current line +across a line break). + +`$` followed by text:: a variable reference. + +`${varname}`:: alternate syntax for `$varname`. + +`$` followed by space:: a space. + +`$$`:: a literal `$`. + +A `build` or `default` statement is first parsed as a space-separated +list of filenames and then each name is expanded. This means that +spaces within a variable will result in spaces in the expanded +filename. + +---- +spaced = foo bar +build $spaced/baz other$ file: ... +# The above build line has two outputs: "foo bar/baz" and "other file". +---- + +In a `name = value` statement, whitespace at the beginning of a value +is always stripped. Whitespace at the beginning of a line after a +line continuation is also stripped. + +---- +two_words_with_one_space = foo $ + bar +one_word_with_no_space = foo$ + bar +---- Other whitespace is only significant if it's at the beginning of a line. If a line is intended more than the previous one, it's @@ -548,37 +588,14 @@ lookup order for a variable referenced in a rule is: Variable expansion ~~~~~~~~~~~~~~~~~~ -Variables are expanded in three cases: in the right side of a `name = -value` statement, in paths in a `build` statement and in paths in -a `default` statement. +Variables are expanded in paths (in a `build` or `default` statement) +and on the right side of a `name = value` statement. When a `name = value` statement is evaluated, its right-hand side is expanded once (according to the above scoping rules) immediately, and from then on `$name` expands to the static string as the result of the expansion. It is never the case that you'll need to "double-escape" a -variable with some syntax like `$$foo`. - -A `build` or `default` statement is first parsed as a space-separated -list of filenames and then each name is expanded. This means that -spaces within a variable will result in spaces in the expanded -filename. - ----- -spaced = foo bar -build $spaced/baz other: ... -# The above build line has two outputs: "foo bar/baz" and "other". ----- - -In a `name = value` statement, whitespace at the beginning of a value -is always stripped. Whitespace at the beginning of a line after a -line continuation is also stripped. - ----- -two_words_with_one_space = foo $ - bar -one_word_with_no_space = foo$ - bar ----- +value to prevent it from getting expanded twice. Future work |