/* $Id: kmkdocs.c 19 2002-10-17 23:02:18Z bird $ * * kmk design and documentation. * * Copyright (c) 2002 knut st. osmundsen * * * This file is part of kBuild. * * kBuild is free software; you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as published * by the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * kBuild is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public License * along with kBuild; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * */ /** @design kmk * * kmk is the make file interpreter and executer in kBuild. It is based on * FreeBSD make but some changes have been made. * * * * @subsection Differences From BSD Make * * The main difference is that kmk doesn't make use of an external shell to execute * commands. It uses it's internal micro shell. This has a number of advantages * when it comes to portability. It also speeds up the execution a little bit. * * The other important difference is default makefile names and order. The names * and order is as follows: *
    *
  1. makefile.kmk *
  2. Makefile.kmk *
  3. makefile *
  4. Makefile *
* * * * @subsection The Micro Shell * * The micro shell provides the basic shell functionality kBuild need - no more, * no less. It is intended to be as simple as possible. * * The shell commands are case sensitive - all lowercase. * * The shell environment variables are case sensitive or insensitive according to * host os. * * * * @subsubsection Command Separators * * There is one command separator '&&'. This works like splitting the command line * into several makefile lines. This splitting isn't done by the micro shell but * the makefile interpreter. * * You might thing this is limiting, but no, you can use all the makefile command * prefixes. * * * * @subsubsection Path Component Separator (/) * * The shell uses '/' as path component separator. * For host OSes with the notion of drive letters or similar, ':' is * used to separate the drive letter and the path. * * * * @subsubsection UNC paths * * For host OSes which supports UNC paths these are supported but for the chdir * command. * * The Path Component Separator is still '/' for UNC paths. * * * * @subsubsection Wildchars * * '*' and '?' are accepted as wildchars. * * '*' means 0 or more characters.
* '?' means 1 character. * * When the term 'pattern' is use in command description this means that * wildchars are accepted. * * * * @subsubsection Quoting * * Use double quotes (") to quote filenames or executables containing spaces. * * * * @subsubsection Execute Program * * If the first, possibly quoted, word of a commandline if not found as an * internal command will be tried executed. If no path it will be searched * for in the PATH environment variable. * * * * @subsubsection Commands * * This section will describe the commands implemented by the shell. * * * * @subsubsubsection copy * Copies one or more files to a target file or directory. * * Syntax: copy [more sources] * * Specify one or more source file patterns. * * Specify exactly one target. The target may be a directory or a file. * If it's a file and multiple source files specified either thru pattern or * multiple source file specifications, the target file will be a copy of the * last one. * * The command fails if a source file isn't found. It also fails on read or * write errors. * * * * @subsubsubsection copytree * Copies one or more files to a target file or directory. * * Syntax: copytree * * Specify exactly one source directory. * * Specify exactly one target directory. The target directory path will be * created if doesn't exist. * * The command fails if source directory isn't found. It also fails on read or * write errors. * * * * @subsubsubsection rm * Deletes one or more files. * * Syntax: rm [file pattern] [more files] * * Specify 0 or more file patterns for deletion. * * This command fails if it cannot delete a file. It will not fail if a file * doesn't exist. It will neither fail if no files are specified. * * * * @subsubsubsection rmtree * Deletes one or more directory trees. * * Syntax: rmtree [directory pattern] [directories] * * Specify 0 or more directory patterns for deletion. * * This command fails if it cannot delete a file or directory. It will not fail * if a directory doesn't exist. It will neither fail if no files are specified. * * * * @subsubsubsection chdir * Changes the current directory. * * This updates the .CWD macro to the new current directory path. * * Syntax: chdir * * * * @subsubsubsection mkdir * Create directory. * * Syntax: mkdir * * Specify one directory to create. * * * * @subsubsubsection rmdir * Remove directory. * * Syntax: rmdir * * Specify one directory to remove. The directory must be empty. * * This command failes if directory isn't empty. It will not fail if * the directory doesn't exist. * * * * @subsubsubsection set * Set environment variable. * * Syntax: set = * * * * @subsubsubsection unset * Unset enviornment variable(s). * * Syntax: unset [more envvars] * * Specify on or more environment variable patterns. * * * * @subsubsubsection pushenv * Pushes a set of environment variables onto the environment stack. The * variables can later be popped back using the popenv command. * * If '*' is specified as pattern the complete enviornment is pushed and * when popped it will replace the enviornment. * * Syntax: pushenv [more envvars] * Syntax: pushenv * * * * * @subsubsubsection popenv * Pop a set of environment variables from the environment stack. If a '*' * push was done, we'll replace the enviornment with the variables poped off * the stack. * * Syntax: popenv * * * * @subsubsubsection echo * Prints a message to stdout. * * Syntax: echo * * Level is verbosity level of the message. This is compared with the * KBUILD_MSG_LEVEL environment variable. The message is suppressed if the * level is lower that KBUILD_MSG_LEVEL. * * The message can be empty. Then a blank line will be printed. * * * */