rules.h

   1 /*
   2  * Copyright 1993, 1995 Christopher Seiwald.
   3  *
   4  * This file is part of Jam - see jam.c for Copyright information.
   5  */
   6
   7 /*  This file is ALSO:
   8  *  Copyright 2001-2004 David Abrahams.
   9  *  Distributed under the Boost Software License, Version 1.0.
  10  *  (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
  11  */
  12
  13 #ifndef RULES_DWA_20011020_H
  14 #define RULES_DWA_20011020_H
  15
  16 #include "modules.h"
  17 #include "jam.h"
  18 #include "parse.h"
  19
  20
  21 /*
  22  * rules.h -  targets, rules, and related information
  23  *
  24  * This file describes the structures holding the targets, rules, and
  25  * related information accumulated by interpreting the statements
  26  * of the jam files.
  27  *
  28  * The following are defined:
  29  *
  30  *  RULE - a generic jam rule, the product of RULE and ACTIONS.
  31  *  ACTIONS - a chain of ACTIONs.
  32  *  ACTION - a RULE instance with targets and sources.
  33  *  SETTINGS - variables to set when executing a TARGET's ACTIONS.
  34  *  TARGETS - a chain of TARGETs.
  35  *  TARGET - an entity (e.g. a file) that can be built.
  36  *
  37  * 04/11/94 (seiwald) - Combined deps & headers into deps[2] in TARGET.
  38  * 04/12/94 (seiwald) - actionlist() now just appends a single action.
  39  * 06/01/94 (seiwald) - new 'actions existing' does existing sources
  40  * 12/20/94 (seiwald) - NOTIME renamed NOTFILE.
  41  * 01/19/95 (seiwald) - split DONTKNOW into CANTFIND/CANTMAKE.
  42  * 02/02/95 (seiwald) - new LEAVES modifier on targets.
  43  * 02/14/95 (seiwald) - new NOUPDATE modifier on targets.
  44  */
  45
  46 typedef struct _rule RULE;
  47 typedef struct _target TARGET;
  48 typedef struct _targets TARGETS;
  49 typedef struct _action ACTION;
  50 typedef struct _actions ACTIONS;
  51 typedef struct _settings SETTINGS ;
  52
  53 /* RULE - a generic jam rule, the product of RULE and ACTIONS. */
  54
  55 /* A rule's argument list. */
  56 struct argument_list
  57 {
  58     int reference_count;
  59     LOL data[1];
  60 };
  61
  62 /* Build actions corresponding to a rule. */
  63 struct rule_actions
  64 {
  65     int    reference_count;
  66     char * command;          /* command string from ACTIONS */
  67     LIST * bindlist;
  68     int    flags;            /* modifiers on ACTIONS */
  69
  70 #define RULE_NEWSRCS   0x01  /* $(>) is updated sources only */
  71 #define RULE_TOGETHER  0x02  /* combine actions on single target */
  72 #define RULE_IGNORE    0x04  /* ignore return status of executes */
  73 #define RULE_QUIETLY   0x08  /* do not mention it unless verbose */
  74 #define RULE_PIECEMEAL 0x10  /* split exec so each $(>) is small */
  75 #define RULE_EXISTING  0x20  /* $(>) is pre-exisitng sources only */
  76 };
  77
  78 typedef struct rule_actions rule_actions;
  79 typedef struct argument_list argument_list;
  80
  81 struct _rule
  82 {
  83     char          * name;
  84     PARSE         * procedure;  /* parse tree from RULE */
  85     argument_list * arguments;  /* argument checking info, or NULL for unchecked
  86                                  */
  87     rule_actions  * actions;    /* build actions, or NULL for no actions */
  88     module_t      * module;     /* module in which this rule is executed */
  89     int             exported;   /* nonzero if this rule is supposed to appear in
  90                                  * the global module and be automatically
  91                                  * imported into other modules
  92                                  */
  93 #ifdef HAVE_PYTHON
  94     PyObject * python_function;
  95 #endif
  96 };
  97
  98 /* ACTIONS - a chain of ACTIONs. */
  99 struct _actions
 100 {
 101     ACTIONS * next;
 102     ACTIONS * tail;           /* valid only for head */
 103     ACTION  * action;
 104 };
 105
 106 /* ACTION - a RULE instance with targets and sources. */
 107 struct _action
 108 {
 109     RULE    * rule;
 110     TARGETS * targets;
 111     TARGETS * sources;        /* aka $(>) */
 112     char      running;        /* has been started */
 113     char      status;         /* see TARGET status */
 114 };
 115
 116 /* SETTINGS - variables to set when executing a TARGET's ACTIONS. */
 117 struct _settings
 118 {
 119     SETTINGS * next;
 120     char     * symbol;        /* symbol name for var_set() */
 121     LIST     * value;         /* symbol value for var_set() */
 122     int multiple;
 123 };
 124
 125 /* TARGETS - a chain of TARGETs. */
 126 struct _targets
 127 {
 128     TARGETS * next;
 129     TARGETS * tail;           /* valid only for head */
 130     TARGET  * target;
 131 };
 132
 133 /* TARGET - an entity (e.g. a file) that can be built. */
 134 struct _target
 135 {
 136     char     * name;
 137     char     * boundname;             /* if search() relocates target */
 138     ACTIONS  * actions;               /* rules to execute, if any */
 139     SETTINGS * settings;              /* variables to define */
 140
 141     short      flags;                 /* status info */
 142
 143 #define T_FLAG_TEMP           0x0001  /* TEMPORARY applied */
 144 #define T_FLAG_NOCARE         0x0002  /* NOCARE applied */
 145 #define T_FLAG_NOTFILE        0x0004  /* NOTFILE applied */
 146 #define T_FLAG_TOUCHED        0x0008  /* ALWAYS applied or -t target */
 147 #define T_FLAG_LEAVES         0x0010  /* LEAVES applied */
 148 #define T_FLAG_NOUPDATE       0x0020  /* NOUPDATE applied */
 149 #define T_FLAG_VISITED        0x0040  /* CWM: Used in debugging */
 150
 151 /* This flag has been added to support a new built-in rule named "RMBAD". It is
 152  * used to force removal of outdated targets whose dependencies fail to build.
 153  */
 154 #define T_FLAG_RMOLD          0x0080  /* RMBAD applied */
 155
 156 /* This flag was added to support a new built-in rule named "FAIL_EXPECTED" used
 157  * to indicate that the result of running a given action should be inverted,
 158  * i.e. ok <=> fail. This is useful for launching certain test runs from a
 159  * Jamfile.
 160  */
 161 #define T_FLAG_FAIL_EXPECTED  0x0100  /* FAIL_EXPECTED applied */
 162
 163 #define T_FLAG_INTERNAL       0x0200  /* internal INCLUDES node */
 164
 165 /* Indicates that the target must be a file. This prevents matching non-files,
 166  * like directories, when a target is searched.
 167  */
 168 #define T_FLAG_ISFILE         0x0400
 169
 170 #define T_FLAG_PRECIOUS       0x0800
 171
 172     char       binding;               /* how target relates to a real file or
 173                                        * folder
 174                                        */
 175
 176 #define T_BIND_UNBOUND        0       /* a disembodied name */
 177 #define T_BIND_MISSING        1       /* could not find real file */
 178 #define T_BIND_PARENTS        2       /* using parent's timestamp */
 179 #define T_BIND_EXISTS         3       /* real file, timestamp valid */
 180
 181     TARGETS  * depends;               /* dependencies */
 182     TARGETS  * dependants;            /* the inverse of dependencies */
 183     TARGETS  * rebuilds;              /* targets that should be force-rebuilt
 184                                        * whenever this one is
 185                                        */
 186     TARGET   * includes;              /* internal includes node */
 187     TARGET   * original_target;       /* original_target->includes = this */
 188     char       rescanned;
 189
 190     time_t     time;                  /* update time */
 191     time_t     leaf;                  /* update time of leaf sources */
 192
 193     char       fate;                  /* make0()'s diagnosis */
 194
 195 #define T_FATE_INIT           0       /* nothing done to target */
 196 #define T_FATE_MAKING         1       /* make0(target) on stack */
 197
 198 #define T_FATE_STABLE         2       /* target did not need updating */
 199 #define T_FATE_NEWER          3       /* target newer than parent */
 200
 201 #define T_FATE_SPOIL          4       /* >= SPOIL rebuilds parents */
 202 #define T_FATE_ISTMP          4       /* unneeded temp target oddly present */
 203
 204 #define T_FATE_BUILD          5       /* >= BUILD rebuilds target */
 205 #define T_FATE_TOUCHED        5       /* manually touched with -t */
 206 #define T_FATE_REBUILD        6
 207 #define T_FATE_MISSING        7       /* is missing, needs updating */
 208 #define T_FATE_NEEDTMP        8       /* missing temp that must be rebuild */
 209 #define T_FATE_OUTDATED       9       /* is out of date, needs updating */
 210 #define T_FATE_UPDATE         10      /* deps updated, needs updating */
 211
 212 #define T_FATE_BROKEN         11      /* >= BROKEN ruins parents */
 213 #define T_FATE_CANTFIND       11      /* no rules to make missing target */
 214 #define T_FATE_CANTMAKE       12      /* can not find dependencies */
 215
 216     char       progress;              /* tracks make1() progress */
 217
 218 #define T_MAKE_INIT           0       /* make1(target) not yet called */
 219 #define T_MAKE_ONSTACK        1       /* make1(target) on stack */
 220 #define T_MAKE_ACTIVE         2       /* make1(target) in make1b() */
 221 #define T_MAKE_RUNNING        3       /* make1(target) running commands */
 222 #define T_MAKE_DONE           4       /* make1(target) done */
 223
 224 #ifdef OPT_SEMAPHORE
 225     #define T_MAKE_SEMAPHORE  5       /* Special target type for semaphores */
 226 #endif
 227
 228 #ifdef OPT_SEMAPHORE
 229     TARGET   * semaphore;             /* used in serialization */
 230 #endif
 231
 232     char       status;                /* exec_cmd() result */
 233
 234     int        asynccnt;              /* child deps outstanding */
 235     TARGETS  * parents;               /* used by make1() for completion */
 236     char     * cmds;                  /* type-punned command list */
 237
 238     char     * failed;
 239 };
 240
 241
 242 /* Action related functions. */
 243 ACTIONS  * actionlist   ( ACTIONS *, ACTION * );
 244 void       freeactions  ( ACTIONS * );
 245 SETTINGS * addsettings  ( SETTINGS *, int flag, char * symbol, LIST * value );
 246 void       pushsettings ( SETTINGS * );
 247 void       popsettings  ( SETTINGS * );
 248 SETTINGS * copysettings ( SETTINGS * );
 249 void       freesettings ( SETTINGS * );
 250 void       actions_refer( rule_actions * );
 251 void       actions_free ( rule_actions * );
 252
 253 /* Argument list related functions. */
 254 void            args_free ( argument_list * );
 255 argument_list * args_new  ();
 256 void            args_refer( argument_list * );
 257
 258 /* Rule related functions. */
 259 RULE * bindrule        ( char * rulename, module_t * );
 260 RULE * import_rule     ( RULE * source, module_t *, char * name );
 261 RULE * new_rule_body   ( module_t *, char * rulename, argument_list *, PARSE * procedure, int exprt );
 262 RULE * new_rule_actions( module_t *, char * rulename, char * command, LIST * bindlist, int flags );
 263 void   rule_free       ( RULE * );
 264
 265 /* Target related functions. */
 266 void      bind_explicitly_located_targets();
 267 TARGET  * bindtarget                     ( char const * target_name );
 268 TARGET  * copytarget                     ( TARGET const * t );
 269 void      freetargets                    ( TARGETS * );
 270 TARGET  * search_for_target              ( char * name, LIST * search_path );
 271 TARGETS * targetchain                    ( TARGETS * chain, TARGETS * );
 272 TARGETS * targetentry                    ( TARGETS * chain, TARGET * );
 273 void      target_include                 ( TARGET * including, TARGET * included );
 274 TARGETS * targetlist                     ( TARGETS * chain, LIST * target_names );
 275 void      touch_target                   ( char * t );
 276
 277 /* Final module cleanup. */
 278 void rules_done();
 279
 280 #endif