Usual invocation is without parameters, in any directory of the project. However, you can modify its behavior by some environment variables and options.
If both environment variable and command line option setting something is specified, command line is taken.
By default, remake opens file REM in current directory and reads instructions from it. If a different directory is specified with parent or descend directives, it opens file called REM in there (note that these directives may specify file as well as directory).
You can change this by:
--file=filename, -f filename options: This changes the file that is read as the first file instead of REM in the current directory.
--default-file=filename option: Changes the file opened when entering a different directory instead of default REM.
$REMAKE_FILENAME environment variable: Acts the same as if both --file and --default-file options were set to its value.
When remake searches for a module to be imported (by the import directive), it searches several directories for file of the given name. The first one found is used. The list contains by default these directories (in order):
$HOME/.remake/modules, if $HOME is set.
/etc/remake/modules.
remake_modules directory in top-level project directory.
The list can be modified by:
--import=directory, -I directory options: Each occurrence of this option adds the directory to the beginning of the list. The last option on the command line will be the first one in the list.
$REMAKE_IMPORT_PATHS environment variable: This variable contains list of directories that will be appended to the end of the list. They are separated by : (colon) character, similarly to the well-known $PATH variable.
Remake stores some data between runs. They are stored in a binary cache, which is usually found in project top-level directory as .rem_cache. This can be changed by the --cache=filename option or $REMAKE_CACHE environment variable.
Usually, remake takes all objects in TARGETS variable, all its dependencies, and runs their methods DEFAULT, if their dependencies changed. There are options to modify this behaviour:
--target=variable_name, -t variable_name options or $REMAKE_TARGETS environment variable: Instead of using variable TARGETS, remake will use this variable to determine the list of objects that are required (their dependencies will be considered too, of course).
--method=method_name, -m method_name: Adds the given method to list of required methods. You can specify it multiple times to ask for more than one method. All of them will be run on all objects required by targets or being their dependencies (if they implement it). If at last one of the methods is considered to be an action (its name present in ACTIONS variable), DEFAULT is run in advance on them.
--define=variable_name=value, -D variable_name=value: This will set a variable of given name to single provided string value. It is placed in a parent context to the toplevel script file (usually REM). You may omit the =value part, in which case the variable becomes undefined (you can remove previously defined variable by this). The value is preserved in cache for future runs of remake, so you do not need to set it every time. Can be used for configuration of features, installation directories and others.
While in theory you shouldn’t need to force recompiling, remake is of development quality and you might make a mistake in writing REM scripts.
--all-run, -r options: Will recompile all objects, no matter if their dependencies changed or not.
--hierarchy-rebuild option: Hierarchy of modules is constructed the first time and stored into cache. This forces remake to build it again and store new hierarchy for future. It will lead into complete recompilation of everything, but all set variables are preserved.
--all-changed, -c options: To know if a dependency changed, remake looks at size and modification time of files and compares it with values stored from last time. This makes it think they all changed from last run. It has similar effect as above, but is internally different.
--nocache option: Loads nothing from cache. This leads to complete recompilation and forgetting all variables configured from command line. New cache will overwrite the old one. It has the same effect as removing the cache file. This may help if the cache gets corrupted and can not be loaded, or when you move your project to a machine with different architecture (the cache is binary and not portable).
--help, -h options: Prints short help text explaining options.
--debug, -d options: When provided with this option, remake will spam its error output with lots of messages about internal behaviour. This is for debugging of remake, not your scripts. This option doesn’t have to be available, depends on how remake was compiled.