ChangeLog update

[k8jam.git] / doc / ChangeLog

  [+] PWD/Pwd built-in added; usage:
      pwd = [ PWD ] ;
  [+] SORT/Sort built-in added; usage:
      sorted = [ SORT $(list) ] ;
  [+] COMMAND/Command built-in added; usage:
      res = [ COMMAND shellcmd-list [[ : options ]] ];
      options:
        exit-status, exit-code:
          return exit code as last list element
        no-output:
          don't return command output
        no-trim:
          don't trim command output;
          default: trim left and right
        no-trim-left:
          don't left-trim command output
        no-trim-right:
          don't right-trim command output
        status-first, code-first:
          put exit code first
        parse-output:
          parse output as list (break on whitespaces -- <= ' ')
        no-space-break:
          don't break on spaces (' ') when 'parse-output' activated
        no-tab-break:
          don't break on tabs ('\t') when 'parse-output' activated
        no-nl-break, no-lf-break:
          don't break on LF ('\n') when 'parse-output' activated
        no-cr-break:
          don't break on CR ('\r') when 'parse-output' activated
      default: ignore command output, return empty string if everything is ok
               or numeric exit code (non-zero)
  [+] COMMAND/Command built-in synthax changed; new synthax:
      res = [ COMMAND shellcmd-list [[ : options ]] ];
      new options (added to common description)
  [+] COMMAND/Command built-in now can parse command output

  [+] rule RemoveOpt
      # VAR = [ RemoveOpt options-to-remove : options-list ] ;
      # remove options from list
  [+] rule RemoveOptWild
      # VAR = [ RemoveOpt regexp-options-to-remove : options-list ] ;
      # remove options from list with egrep-like regexps
  [+] rule profile
      # profile "name" ;
      # set compile flags for profile; works only for gcc/g++
      # available profiles:
      #  none, default: don't change
      #  empty: remove optimisation flags
      #  speed: optimise for speed and pIII
      #  size: optimise for size
      #  debug: don't optimize, add debug info
      #  standard: -O2
  [+] rule ObjectNoAliasing
      # ObjectNoAliasing filelist ;
      # turn off aliasing optimization for specified files
      # works only for gcc/g++

  [*] MainC++ wasn't working properly
  [*] XXXC++ variables changed to XXXC++ZZZ (MainC++ --> C++Main)
  [+] LOCATE_BIN and ALL_LOCATE_BIN variables added (for Main and MainC++ targets)
      so now one can do something like this:
        ALL_LOCATE_TARGET = $(TOP)/build/obj ;
        ALL_LOCATE_BIN = $(TOP)/build ;
      and have a nice bunch of *.o files in build/obj and binary in build/
  [+] new rule: lib-config
      call $(1) --cflags and $(1) --libs (many libs provides such configurators)
      add necessary flags to compiler and linker vars
      return "tan" (non-empty string) if library is present
      if $(2) != "" -- don't add flags, just check
  [+] PATH_SEPARATOR variable added
  [*] build process changed (.o and .a moved to subdir)
  [+] allow []...] and [^]...] in globs (so ranges can include ']')
  [+] :Q now quotes all special shell chars, not only '\'
  [*] some regexprs was broken by tab expansion; fixed
  [*] OPTIMC++ renamed to C++OPTIM

  [+] LOCATE_LIB, LOCATE_LIBSO and ALL_LOCATE_LIB[SO] variables added (for Library and SharedLibrary targets)
      so now one can do something like this:
        ALL_LOCATE_TARGET = $(TOP)/build/obj ;
        ALL_LOCATE_LIB = $(TOP)/build/liba ;
        ALL_LOCATE_LIBSO = $(TOP)/build/libso ;
        ALL_LOCATE_BIN = $(TOP)/build ;
      and have a nice bunch of files in various dirs.

  [*] JAMCMDARGS now set before parsing Jamfiles (and what sense was to set it after? %-)
  [+] JAM_TARGETS variable added; scripts are free to modify it, so we can easy define targets from whithin

  [+] SubIncludeOnce varname : TOP ... ;
      will do SubInclude iff 'varname' is not set (and will set 'varname')
      so one can include all necessary libraries in all necessary projects

  [+] partial Objective C support:
      ObjC-Main, std. set of OBJC* vars
        OBJC_GNUSTEP_BASE_LIB = gnustep-base ;
        OBJC_GNUSTEP_GUI_LIB = gnustep-gui ;
      rules: ObjCUseGNUstepBase, ObjCUseGNUstepGui, ObjCUseGNUstep

  [+] 'lib-config-ex' rule:
      lib-config-ex "command" : "var-name-to-modify"
      "var-name-to-modify" can be omited;
      rule returs value of command

  [+] new built-ins:
      Echo-n: same as Echo, but does not writes '\n'
      O-Flush: flush standard output (for Echo-n)
  [+] added rules: LinkFlagsOn, C++LinkFlagsOn, ObjCLinkFlagsOn
      same as Object*Flags, but for linker flags
      we need this due to 'gristing' in multidir builds

  [+] new variable: JAM_FORCE_GCC_OPTIONS
      set it to override GCC detection

  [+] rule set-profile:
      selects 'debug', 'standard', 'speed' or 'size' profile according to vars:
        DEBUG = 1 : debug
        OPT_SIZE = 1 : size
        OPT_SPEED = 1 : speed
        default: standard

  [+] rule set-default-subdir-locates (sets my defaults for ALL_LOCATE_XXX: _build/, etc)

  [+] alias for set-default-subdir-locates: set-default-target-locations ;

  [+] rule pkg-config

  [+] jam now correctly creates dirs for files like 'dir/source'
  [+] alias for set-default-subdir-locates: set-default-locations ;

  [+] added acions for WINDOZE=1 (my own way to cross-build windoze soft with wine and mingw)
      vars for invocation:
        WINE -- wine command; default is "wine"
        MGPATH -- path to mingw bin dir; default is "c:\mingw\bin\" (note the last '\')
        MGCC -- mingw gcc compiler name; default is "mingw32-gcc.exe";
        MG -- mingw g++ compiler name; default is "mingw32-g++.exe -static-libgcc"
      vars for 'windoze-fix' rule (this rule should be invoked in Jamrules; it is harmless to
      invoke it for any build scheme):
        WINDOZE_THREADS -- if not empty, add "-mthreads"
        WINSUBSYS -- either 'console' or 'windows'; default is 'console'
        WINLIBS -- list of windoze libraries to add; default is '-lkernel32'

  [!] WARNING! COMPATIBILITY BREAKING CHANGE!
  [*] old SubInclude rule renamed to SubIncludeMany
  [*] new SubInclude rule works as SubIncludeOnce (autogenerates guard var)

  [+] new built-in: [ ExprI1 num0 op num1 ]
      integer math; understands 5 standard ops ('%' as C '%')
      [ ExprI1 40 + 2 ] ==> "42"
      it also understands "<", "<=", ">", ">=", "=" and "!="
  [+] [ ExprI1 "#" string ] -- return string length
  [+] new built-in: [ Split str : delims ]
      split `str` using `delims`
        [ Split "a,b,c;d" : ",;" ] ==> a b c d
      if `delims` is not specified, split string to chars

  [+] lexer now needs less spaces (and sometimes more quoting)
  [+] added header caching (when using set-default-locations rule)

  [+] new build-in: [ NormPath pathstr ]
      it will add 'pwd' if path is not absolute and will try to resolve some '.' and '..'
      (only leading '..' though).
      it can be used in SubDir replacement to automate dir building

  [+] added 'rule name expansion':
        rule print-foo { Echo "foo" ; }
        variable = "print" ;
        $(variable)-foo ;

  [+] added default 'help' and 'push' targets
      redefine actions AShowHelp and AGitPush in Jamrules to use the correspoinding target

  [+] added help-profile target

  [+] new variables: CFLAGS.all, OPTIM.all, LINKFLAGS.all, LINKLIBS.all
      profile now sets *.all flags

  [+] K8JAM-PROGRESS-TIME-DELTA variable (float, seconds between progress/time indicator)

  [+] regexp engine now undestands some character classes (like :space:) and non-greedy ops

  [+] call 'check-setup-windoze' rule to enable WINDOZE=1 builds
  [+] setup-windoze rule will setup windoze build regardless of WINDOZE=1
  [+] call use-mingw32 rule to use i686-pc-mingw32 crosscompiler instead of wine
  [+] call windoze-fix after setting WINDOZE_THREADS, WINLIBS and WINSUBSYS

  [+] sys-has-command cmd -- perform `which`, return "tan" or ""

  [+] new built-in: ListLength

  [+] `PreUserObject` rule
      this rule will be called before `Object` rule decides how to build something;
      the calling convention is the same as for `UserObject`, but `PreUserObject`
      should return non-empty string if it wants to bypass default generator rules.

  [+] documentation: built-in DependsList
      DependsList all ;
      returns a list of child dependencies for a given target

  [+] new built-ins: HaveRule, HaveActions
      HaveRule rulename [rulename...] [ : glob/regexp case-insensitive ignore-case ]
      HaveActions rulename [rulename...] [ : glob/regexp case-insensitive ignore-case ]
      returns non-empty string if all specified rules or actions are defined
      note that we can have rule without actions and actions without rule
      specify `glob` option to treat names as shell-like globs
      specify `regexp` option to treat names as regexps
      specify `case-insensitive` option to ignore case

  [+] new built-in: ForceFile
      reverts NoFile effect

  [+] added flags to Glob and Match: now we can use globs and regexps, and do
      that ignoring the case.

  [+] new rule: FileExists fname [fname...] ;
      returns non-empty string if all files exists; understand pathes.

  [+] Glob flags:
        case-sensitive
        case-insensitive
        ignore-case
        glob
        regexp
        plain
        dirs-only
        files-only
        any
        names-only
        full-path

  [+] set-default-locations now recognizes DEBUG and respects BUILD_DIR

  [+] new variables: CC.standard and C++.standard; defaults to gnu99 and gnu++98 if set-profile called

  [+] new rule: DetectLibrary libnames [: includes [: pathes]]
      default path list is $(DETECT_LIBRARY_PATH)
      it will check $(p)/lib for library and $(p)/include for header
      returns prefix or empty list
      usage:
        LIBJIMTCL_PFX = [ DetectLibrary libjim.a : jim.h : /opt/jim /opt/jim-tcl ] ;
        if $(LIBJIMTCL_PFX) {
          LINKFLAGS.all += -L$(LIBJIMTCL_PFX)/lib ;
          LINKLIBS.all += -ljim ;
          HDRS += $(LIBJIMTCL_PFX)/include ;
          DEFINES += USE_JIM_TCL ;
        }

  [+] you can set K8JAM-JOBS variable to force number of jobs

  [+] use DBG=1 to suppress NDEBUG define for non-debug profiles

  [+] easy independent targets in *Main:
      specify independent target name as 3rd arg to *Main:
        Main alsatest : alsatest.c : alsatest ;  # or Main alsatest : alsatest.c : _ ;
        Main zytest : zytest.c : test tests ;
      to cleanup, do:
        jam alsatest_clean
      or
        jam alsatest clean

  [+] 'clean' now doesn't clean 'Jamrules.auto.configure'; use 'distclean' to kill it

  [+] JAMCONFIGARGS variable, which collects --* arguments
  [+] 'config' now understands '--prefix' and sets PREFIX =? xxx
  [+] InstallUserDefined rule:
        # $(1): gristed source file
        # $(2): source file
        # $(3): directory to install
        # $(LOCATE): the same as $(2) -- can be used in actions

  [+] -configure-detect-library- now allows additional parameters (allow-any-lib and allow-any-header)
      as parameter #7

  [+] *Main now understands some flags, which must be specified after file name:
      Main mysoft :
        main.c
        processing.c !no-aliasing  # add OPTIM_NOALIAS to build command
      ;
      '!xyz' actually calls rule named --main-option-xyz-- if any, passing GRISTED filename as $(1) and
      UNMODIFIED file name as $(2). sample no-aliasing rule:
      rule --main-option-no-aliasing-- {
        if $(OPTIM_NOALIAS) {
          CCFLAGS on $(1) += $(OPTIM_NOALIAS) ;
          C++FLAGS on $(1) += $(OPTIM_NOALIAS) ;
          OBJCFLAGS on $(1) += $(OPTIM_NOALIAS) ;
        }
      }
      use '!!filename' if your file name starts with '!'

  [+] -configure-pkg-config-necessary- rule
      optional: set PROJECT_NAME to project name which should be displayed on failure
      -configure-pkg-config-necessary-
        "GLib"    "glib-2.0 >= 2.30.0"
        "X11"     "x11"
        "GTK+2"   "gtk+-2.0"
      ;

  [+] -configure-enable-disable-vars- variable to easy '--enable-xxx' and '--disable-xxx' options:
      # "auto": check with pkg-config or so, show '--disable-xxx'
      # "": disabled by default, show '--enable-xxx'
      # non-empty string: enabled by default, show '--disable-xxx'
      -configure-enable-disable-vars- +=
        "sqlite"    USE_SQLITE    "auto"  "don't use sqlite"
        "gtkhtml"   USE_GTKHTML   "auto"  "don't use GTKHTML"
        "gtkspell"  USE_GTKSPELL  "auto"  "don't use GTKSpell"
        "svg"       USE_RSVG      "auto"  "don't use librsvg"
        "soup"      USE_SOUP      "auto"  "don't use libsoup"
        "curl"      USE_CURL      "auto"  "don't use libcurl"
        "dock"      USE_DOCK      "tan"   "disable dock icon"
      ;

  [*] Exit ; now exits without output and with SUCCESS exit code

  [+] PROFILE variable now selects profile in set-profile rule

  [+] RandName rule: generate random name
      [ RandName ] -- /tmp/XXX
      [ RandName "abc/" ] -- abc/XXX
      [ RandName "" ] -- XXX

  [+] ListWrite rule: write string list to file
      ListFileWrite filename : list [: terminator] [: append]
      default terminator is '\n'
      return success flag

  [+] -configure-try-compile-cc- rule
      $(1) -- program, string list
      $(2) -- additional compiler flags (optional)
      $(3) -- additional linker flags (optional)
      rule -configure-test-timegm- {
        return [ -configure-try-compile-cc-
          "#include <stdlib.h>"
          "#include <time.h>"
          "int main() {"
          "struct tm _tm = { 0 };"
          "_tm.tm_year = 2000;"
          "_tm.tm_mon = 1;"
          "_tm.tm_mday = 1;"
          "timegm(&_tm);"
          "return 0;"
          "}"
        ] ;
      }

  [+] -configure-test-compile-cc- rule:
      $(1) -- test name
      $(2) -- program, string list
      $(3) -- additional compiler flags (optional)
      $(4) -- additional linker flags (optional)

  [*] Echo-n removed, O-Flush removed, Echo now accepts some flags as $(2):
      -n -- don't write newline
      -Q -- don't write anything (so Echo : -n -Q will effectively do fflush(stdout);)
      -S -- don't print spaces betwen args
      -s -- print space after last arg (if there were some args at all)
      -w -- use stderr instead of stdout

  [*] Exit now accepts the same $(2) args as Echo

  [+] semaphores (TOTALLY UNTESTED!)
      It is sometimes desirable to disallow parallel execution of some actions. For example:
      Old versions of yacc use files with fixed names. So, running two yacc actions is dangerous.
      One might want to perform parallel compiling, but not do parallel linking, because linking
      is i/o bound and only gets slower. Craig McPeeters has extended Perforce Jam to solve such
      problems, and that extension was integrated in Boost.Jam (and in k8jam).

      Any target can be assigned a semaphore, by setting a variable called JAM_SEMAPHORE on that
      target. The value of the variable is the semaphore name. It must be different from names of
      any declared target, but is arbitrary otherwise.

      The semantic of semaphores is that in a group of targets which have the same semaphore, only
      one can be updated at the moment, regardless of "-j" option.

  [+] binding rules
      Whenever a target is bound to a location in the filesystem, K8Jam will
      look for a variable called BINDRULE. If non-empty, $(BINDRULE[1]) names
      a rule which is called with the name of the target and the path it is
      being bound to. The signature of the rule named by $(BINDRULE[1]) should
      match the following:

        rule bind-rule target : path

      This facility is useful for correct header file scanning, since many
      compilers will search for #included files first in the directory
      containing the file doing the #include directive. $(BINDRULE) can be
      used to make a record of that directory.

  [+] for local var in xyz { ... }

  [+] strings in single quotes -- '\' in such strings is just an ordinary character
      to embed single quote in such string use "''" (two single quotes in a row)
      this is useful for regular expressions

  [+] define -configure-user-help- rule to show user 'configure' options

  [+] single-quoted strings now should not be expanded. i.e. '$(a)' means literal
      string "$(a)", not string with value of $(a) expanded.

  [+] ListRemoveDuplicates rule added. *Main now will remove all duplicate '.o' from
      linking list.

  [*] heavily modified GenFile rule:
       GenFile target : image sources [: dependencies ] ;

       Runs the command "_image_ _target_ _sources_" to create _target_ from
       _sources_ and _image_ (where _image_ is an executable built by the @Main rule).
       'source' starts with '-' or '/' is an option, don't include it in dependency graph.
       'source' starts with '*' switches generator to GenFile2, which will not automatically
       add target to argument list.
       'source' equals to $$ means 'target' and switches to GenFile2.
       if 'image' starts with ':', this is standalone file, don't append any suffix to it.

  [+] added 'UserObject' rule chain. define rule with arbitrary name and signature:
      / <grist>outfile.o : <grist>infile.ext : exetarget ;
      then add it to chain with 'RegisterUserObjectRule rulename'.
      'rulename' should return true if it is in effect (to break chain).
      if no rule in chain in effect, standard 'UserObject' rule will be called.

  [+] added $(out) and $(in) as aliases for $(1) and $(2) (tnx to tzirechnoy)

  [+] added `~=` for regexp comparison:
      $(a) ~= '^hey!$'

  [+] all regexps now can contain options. if regexp starts with '/', it MUST
      be closed with '/' too, and can have such options after it:
        i: ignore case
        u: this is utf-8 string
        m: '.' matches newline
      default mode: case-sensitive non-utf-8, '.' will not match newline

  [*] new variable expander: bigger, better and uncut!
      WARNING! selector logic changed!
      you can do the things like this now:
        a = /usr/local/bin/fuck.elf ;
        Echo $(a:B=heh:BS) ;
      previously this prints 'fuck.elf', but now it prints 'heh.elf'

  [*] Q modifier extended: now it can have '=qset' argument; it will use
      first char from qset as 'screening' char and other chars as chars
      that must be screened. if there is only one char, it will use
      'shell quoting set'.

  [*] new scanner; sometimes better, sometimes worst. samle of better:
      $(a:Q=\\/) -- no more "\\\\" here!

  [+] :W=width: pad string to the given width; if width<0: left padding
  [+] :W -- return string length
  [+] :C=width: cut string to the given width

  [-] NormPath
  [+] NormalizePath path [: pwd ]
      prepend 'pwd' if path is not absolute (use current working dir if no 'pwd' given).
      resolve '.' and '..' (it will not use filesystem for this, just string processing).
      if path ends with '/', result will end with '/' too

  [*] FReverse rule removed: use ListReverse instead.

  [+] k8jam will try to load ~/.jam.rc before main Jamfile. you can use it to disable
      idiotic 'diagnostic caret' in gcc 4.8+. just put this to ~/.jam.rc:
        CFLAGS.all += -fno-diagnostics-show-caret ;

  [+] if user-set-subdir-locates rule is present, it will be called from set-target-locations
      after jam locations processed, with built dir as arg. rule MUST return dir

  [+] added UNITTEST, RELEASE and NODEBUG flags for D

  [+] -configure-pkg-config-var- rule: the same as -configure-pkg-config- but 1st arg is
      'enable/disable' var name. var value will be changed accordingly to check result

  [+] D support in set-profile:
      RELEASE=1 -- build release version
      UNITTEST=1 -- build unittest version
      for non-release mode:
        D_NO_ASSERT=1: turn off assert()
        D_NO_IN=1: turn off in {}
        D_NO_OUT=1: turn off out {}
        D_NO_INVARIANTS=1: turn off invariant {}
        D_NO_BOUNDS=1: turn off bounds checking
        D_NO_DEBUG=1: turn off 'debug'
        D_DEBUG=list: add -fdebug=xxx for each list item
        D_MAXSPEED=1: DON'T USE!

  [+] set-profile now understands 'speed', 'size', 'debug' and 'release' targets
      'release' target sets RELEASE variable and some flags for GDC compiler

  [+] set-profile now accepts list of flags. known flags:
        no-targets -- don't process 'profile targets'

  [-] no more D_RELEASE and D_UNITTEST

  [+] D_VERSION variable; works similar to DEFINES but for gdc

  [+] TARGET_SUBDIR variable, contains custom subdir for targets set with set-target-locations.
      can be used to differentiate builds by specifying CLI vars or so
      if it's a list, it will be joined with PATH_SEPARATOR

  [+] ObjectDFlags rule

  [+] ObjectDInlineFlags rule which adds $(GDC_INLINE_FLAGS) to force gdc do maximal inlining
      without resorting to -O3

  [+] added HDRPATH_IGNORE var which contains list of path prefixes to ignore in header scanner

  [+] you can list libxyz.a in Main rule now, this will work exactly as LinkLibraries

  [+] added JAM_BINARY var, which can be used in Command to exec ourself

  [+] added "jammod" command to invoke various k8jam modules

  [+] added "genman" module