ME(1)                            User Commands                           ME(1)

NAME
       me - MakeMe -- Utility to make and manage programs and products

SYNOPSIS
       me
           --benchmark
           --configuration
           --configure /path/to/source
           --continue
           --debug
           --deploy directory
           --depth level
           --diagnose
           --dump
           --endian [big|little]
           --file file.me
           --force
           --gen [make|nmake|sh|vs|xcode|main|start]
           --get field
           --help
           --import
           --keep
           --log logSpec
           --nolocal
           --nocross
           --out path
           --overwrite
           --platform os-arch
           --pre
           --prefix dir=path
           --prefixes [debian|embedthis|opt]
           --profile [debug|release|...]
           --quiet
           --rebuild
           --reconfigure
           --release
           --rom
           --set [feature=value]
           --sets [set,set,...]
           --show
           --static
           --unicode
           --unset feature
           --version
           --verbose
           --watch msec]
           --why]
           --with PACK[=PATH]
           --without PACK
           [targets|actions] ...

DESCRIPTION
       MakeMe  and  its  "me"  command is modern replacement for the venerable
       make and not so popular autoconf utilities.  MakeMe manages the  build-
       ing  of  programs  and products by effectively determining which pieces
       have been updated and thus which components need to be rebuilt. It eas-
       ily handles direct compilation and generation of projects.

WHY ME?
       Many projects rely on autoconf to configure products and make to build.
       But autoconf is a baroque maze of scripts and make is low-level, scales
       poorly  and  provides little support for easily building executable and
       libraries in a cross platform  manner.  Furthermor,  neither  of  these
       tools work well for Windows or embedded platforms like VxWorks.  Conse-
       quently, creating portable Makefiles and  autoconf  scripts  that  will
       work  on  a  variety  of  platforms and support cross-compilation is an
       exercise in patience. Often the result is slow, fragile build  systems,
       especially on Windows.

       MakeMe  replaces  both  autoconf  and make with a single utility: 'me'.
       MakeMe provides a higher level of abstraction  to  easily  specify  the
       targets to build (libraries, executables, files and script output).  It
       can build directly on Linux, Mac or Windows and cross compile for other
       platforms.  It  will generate native projects for Visual Studio, XCode,
       Make, Nmake and shell scripts. MakeMe builds fast without the  complex-
       ity of autoconf and make.

       MakeMe  was  initiated  after evaluating Make, CMake and GYP for use by
       Appweb and Ejscript  in  an  embedded,  cross-compilation  environment.
       While  all three can be made to work, at Embedthis, we were expending a
       large percentage of time on the build system and  less  on  the  actual
       product. Our design goals were:

           . Create a build too to be used by Embedthis for its own products
           . Be portable across the major Unix platforms and Windows
           .  Easily manage cross-compilation and cross-compilers for embedded
       targets
           . Generate native projects for IDE integration
           . Build quickly, reliably and flexibly on Windows without requiring
       Cygwin
           .  Support for the entire build cycle: C dependencies, compilation,
       test and packaging
           . Support  modular  discovery,  configuration  and  integration  of
       external third-party packages
           . Be hackable and extendable

FEATURES
       MakeMe has the following major features:

           . Configuration and component discovery (replaces autoconf)
           . Compiler capability sleuthing
           . Generation of a configuration source header (me.h)
           .  Generation of Xcode, Visual Studio, Make, Nmake and shell script
       projects
           . Automatic C/C++ source code dependencies
           . Projects can aggregate multiple MakeMe files without using recur-
       sion
           . Cross platform. Easily handles Windows, Linux and Mac builds
           . Easy cross-compilation
           . Building outside source tree for read-only file systems
           .  MakeMe  files  are Javascript source and are easily modified and
       extended
           . Multiple build profiles (debug, release, ...)
           . Very fast configuration and building, even on windows

NICE BITS
       While MakeMe has a strong feature set, there are  some  characteristics
       that make building with MakeMe especially nice:

           . Unified project view. No "make" style recursion required.
           . MakeMe configuration may be comprised by multiple MakeMe files
           .  MakeMe file targets and scripts are relative to their own direc-
       tory
           . Targets can be named symbolically not just by the target path.
           . MakeMe provides a "why" option (me -why) to display why a  target
       was or was not rebuilt
           .  MakeMe  files and targets intelligently inherit of outer project
       properties
           . MakeMe scripts run using the working directory of the MakeMe file
           . Detailed documentation

OVERVIEW
       A  MakeMe file is a Javascript file with a '.me' extension that invokes
       Me.load() to process a set of build instructions.  The  build  instruc-
       tions are expressed as a Javascript object literal that Me.load() inte-
       grates into the master set of build instructions.

            Me.load({
                targets: {
                    /* Build the rocket executable */
                    rocket: {
                        type: 'exe',
                        sources: ['*.c'],
                    },
                },
            })

       To build the rocket, enter:

            me rocket

INVOCATION
       When 'me' is invoked, it searches for a 'start.me' file in the  current
       directory.  If  one  if  not found, it searches up the parent directory
       chain for one. MakeMe then loads this  'start.me'  file  and  commences
       processing  its  build instuctions. A 'start.me' may in turn load other
       MakeMe files.

STANDALONE USES
       A standalone start.me file may be used to express simple build  targets
       that do not requiring any prior configuration step. The 'start.me' file
       contains targets that specify the recipies to build those targets.

CONFIGURED PRODUCTS
       Some products require a configuration  phase  prior  to  building  with
       MakeMe.  Configuration  involves  discovering  the tools and components
       available on the current system and the available compiler  tool  chain
       support.   For  configured products, 'me' is first invoked with a "con-
       figure" target. MakeMe then reads a 'main.me' file which describes  the
       project,  and  generates  a  'start.me'  and  'platform.me'  file  that
       describes the system.

TARGETS
       MakeMe is typically invoked with zero or  more  targets  to  build.  If
       invoked  with  zero targets, MakeMe will build all the out-of-date tar-
       gets. If a one or more targets are specified, only those  targets  will
       be brought up to date.

       To build all targets:
            me

       To build several named targets:
            me libengine librocket space-program

       MakeMe pre-defines several targets:

           . configure - To configure prior to building
           . build - To build all targets
           . compile - Same as 'build'
           . clean - To clean built targets and prepare for rebuilding
           . rebuild - Clean and build

CONFIGURING
       To  configure  a product before building, run MakeMe using the 'me con-
       figure' target or alternatively use the '-config' switch.  When config-
       uring,  MakeMe  will load a 'main.me' file and use the details from the
       'settings' properties to tailor the configuration. The settings provide
       a 'name', 'description', and 'version'.

       For example, this is a typical 'settings' configuration.

            settings: {
                name: 'mpr',
                description: 'Multithreaded Portable Runtime',
                version: '4.0.5',
            },

            The  'configure' properties define the required and optional pack-
            ages that should be discovered.

            configure: {
                requires: [ 'osdep' ],
                discovers: [ 'ssl' ],
            },

       The 'requires' property defines the packages that are  required  to  be
       present on the system to build. The

CROSS COMPILING
       To  build  a product for platform different to that of the local system
       is called cross compiling. Sometimes this cross compiling is just for a
       different  instruction  set (say x64 instead of x86). Other times it is
       for a completely different operating system and/or CPU architecture. In
       such  cases  a  cross-compiler  may be required to build for the target
       platform.

       MakeMe supports cross compiling via the 'me -platform  OS-ARCH  config-
       ure'  switch.  This adds a platform to the list of platforms to be made
       when building. Multiple platforms may  be  specified  and  the  'local'
       platform alias may be used for the local development platform.

       Some products require local building to make tools that are required to
       build for any platform. These products  add  a  "platforms:  ['local']"
       property  to  their settings collection in the main.me file. This auto-
       matically adds the local platform to the platforms list and is the same
       as adding '-platform local' on the command line when configuring.

            me --platform windows-x64-debug -configure .

       This  will  create  a  windows-x64-debug.me  configuration  file  and a
       start.es that references it. The platform switch does not  need  to  be
       respecified after configuration.

PROJECT GENERATION
       MakeMe can generate generate complete project files for building using:
       make, nmake, Visual Studio, Xcode or plain shell scripts.  MakeMe  uses
       the  '--gen' switch to specify the projects to build. MakeMe is capable
       of cross-generating projects for non-native platforms. For example: you
       can generate an Xcode project for Mac OS X on a Windows system.

            me -continue -platform macosx-x64 configure -gen xcode,make,sh

       This will generate Xcode, make and shell script projects for a Mac OS X
       64-bit. The continue switch indicates that generation  should  continue
       even  if  the required compilers and build tools are not present on the
       development system.

DEPENDENCIES
       MakeMe targets can depend on other targets that must  be  built  first.
       MakeMe  targets  have a name which may be depended upon by another tar-
       get. For example:

            targets {
                first: {
                    build: "print('Build First')",
                },
                second: {
                    depends: ['first'],
                    build: "print('Build Second')",
                }, }

       Before MakeMe begins building, it parses the entire MakeMe file config-
       uration  and  determines  which targets depend on what.  It then builds
       the targets in the required build order. It  successfully  detects  and
       handles dependency loops.

DEFAULTS
       Often  targets  need  very  similar  configuration.  MakeMe  provides a
       'defaults' set of properties that are inherited by all targets. It also
       provides an 'internal' set of properties that are inherited by only the
       targets in the same MakeMe file. For example:

            defaults: {
                '+defines': [ 'TUNE=SPEED ],
                '+libraries': [ 'math' ],
            }

       This will use the  'TUNE=SPEED'  compiler  define  when  compiling  all
       source  files,  and  the  'math'  library when linking executables (and
       libraries on some systems).

OVERRIDING
       MakeMe has default command flags for the  compiler,  linker  and  other
       tools.  These can be overridden by providing environment variables con-
       taining alternate flags to use. Use CFLAGS to provide  compiler  flags,
       DFLAGS for pre-processor definitions, IFLAGS for compiler include paths
       and LDFLAGS for linker flags. If these flags are provided to 'me'  when
       building,  they  apply  to that run only. If the flags are provide when
       configuring, they are saved in the generated platform file and apply to
       all subsequent runs.

DEBUGGING
       With  Make  and  other  build tools, it is difficult to determine why a
       target is or is not being built. MakeMe provides a  '--why'  switch  to
       diagnose  problematic  build sequences. This switch displays the reason
       why each target was or was not built.

       In a complex project containing many MakeMe files, it can be helpful to
       see  the  entire  MakeMe  configuration  in  one file. Use the '--dump'
       switch to save a copy of the entire configuration. In the  dump,  build
       defaults  are  fully expanded to each target contains the expanded con-
       figuration that will be used to build the target.

       By default, MakeMe builds relativley quietly and  stops  on  the  first
       build  error.  To  see the commands MakeMe is issuing, use the '--show'
       switch. To build totally quietly, use the '--quiet' switch. To continue
       building despite build errors, use the '--continue' switch.

OPTIONS
       --benchmark
              Measure the elapsed time to run 'me'.

       --configuration
              Display  the current configuration. This displays the configura-
              tion for each package and the build settings.

       --configure /path/to/source/tree
              Configure the project to prepare for building.  This  configures
              MakeMe for building the project based on the instructions speci-
              fied in a 'main.me' located in the specified path  source  tree.
              When run, 'me' will create a platform configuration MakeMe file,
              a build output directory  and  me.h  header.  The  configuration
              directory  is of the form: build/OS-ARCH-PROFILE where OS may be
              freebsd, linux, macosx, solaris, vxworks, windows  and  ARCH  is
              arm, mips, ppc, x64 or x86. PROFILE is typically set to debug or
              release. For example: 'build/macosx-x64-debug'.

              MakeMe will  use  the  settings.required  and  settings.discover
              properties  in  the main.me for a list of packages to use.  When
              configuring, MakeMe will search for these packages and will cre-
              ate  definitions in the configuration MakeMe file for later use.

       --continue
              Continue to build despite any build errors. Normal operation  is
              to stop building if any build errors are encountered.

       --debug
              Same as --profile debug

       --deploy directory
              Install  the product to the deployment directory. This is useful
              to stage the required files to install on a system.  Use  --sets
              to define the file sets to deploy.

       --depth level
              Set the unit test depth level.

       --diagnose
              Run MakeMe with stack backtrace display on errors.

       --dump Dump  the  aggregate  MakeMe  configuration  into  a single dump
              MakeMe file.

       --endian [big|little]
              Set the CPU endianness. This is normally detected  by  the  com-
              piler but may be overridden by this switch.

       --file filename
              Use  the  alternate  named  MakeMe  file  instead of start.me or
              main.me.

       --force
              Override warnings and proceed with the  operation.  See  --over-
              write to write over existing files.

       --gen [make|nmake|sh|vs|xcode|main|start]
              Generate  files.  This  option  can  be used to generate initial
              start.me or main.me files or IDE  project  and  makefiles.   The
              --gen  start,  option can be used to create a stand-alone sample
              start.me file. The --gen main, option can be used  to  create  a
              sample  main.me file when starting a new product.  Project files
              are created under the 'projects' directory.   The  projects  are
              based   on   the   current  configuration.  If  cross-generating
              projects, you will typically need to also use -configure.

       --get field
              Get a field from the MakeMe DOM. This can be used to display any
              MakeMe  file value. Unlike --set, this applies to any MakeMe DOM
              value and not just to settings.  For  example:  'me  --get  set-
              tings.version'.

       --import
              Import the standard MakeMe configuration "makeme" directory into
              the local source tree.

       --keep Keep some intermediate build files. This is  currently  used  by
              some documentation generation targets.

       --log logName[:logLevel]
              Specify  a  file to log internal execution messages. MakeMe will
              log execution related trace to the log file. The log level spec-
              ifies the desired verbosity of output. Level 0 is the least ver-
              bose and level 5 is the most. The '-v' switch is  an  alias  for
              '--log stderr:2'.

       --nocross
              Don't  cross-build. Build only for the local development system.

       --nolocal
              Don't build for the local development system. Build only for the
              cross platforms.

       --out path
              Save  MakeMe trace output to a file instead of displaying to the
              console.

       --overwrite
              Overwrite existing files.

       --platform os-arch
              Add a platform to build for  cross-compilation.  Multiple  plat-
              forms  can be added. You may use 'local' for the local platform.
              Options specified after the platform apply to  the  prior  plat-
              form. For example:

                  me  --platform  linux-x86 --without all --platform linux-arm
              --with ejscript configure

       --pre  Pre-process a source file to stdout.

       --prefix dir=path
              Set the installation directory prefix. Various products  utilize
              different  prefixes.  Typical  prefixes  are: root, base, state,
              data, app, vapp, bin, etc, inc, log, spool, src, web.  For those
              familiar  with autoconf, the major autoconf prefixe switches are
              supported and mapped as follows: --prefix to root,  --bindir  to
              bin,  --libdir to lib, --includedir to inc, --sysconfdir to etc,
              --libexec to app, --logfiledir to log, --htdocsdir to  web,  and
              --manualdir to man.

       --prefixes debian|embedthis|opt
              Select  an  installation  prefix  package.  Debian specifies the
              debian recommended installation  locations.  Embedthis  products
              install  by  default with a prefix of /usr/local/lib/PRODUCT and
              symlink exectuables  to  /usr/local/bin.   The  opt  prefix  set
              installs with a prefix of "/opt".

       --profile [debug|release|...]
              Use the specified profile when building. This option is provided
              once when configuring and the  result  is  saved  in  the  plat-
              form.profile  property  in the platform.me file. Custom profiles
              can be added to the main.me or start.me files.

       --quiet
              Quiet operation. Suppresses output trace.

       --rebuild
              Rebuild the specified targets. Can also use 'me rebuild'.

       --reconfigure
              Re-run configuration using the prior configuration settings.

       --release
              Select the release profile. Same as --profile release.

       --rom  Configure setting to build for systems without  a  file  system.
              This  enables  the  ROM file system.  Use the makerom utility to
              process required files into C source code for building with  the
              application.

       --set key=value
              Set  a settings property to a given value. For example: 'me -set
              version=1.0' will update  the  settings.version  property.   Use
              this  when running 'me configure' to persist your changes in the
              configuration MakeMe file.

       --sets [set,set,...]
              Define the groups of files to install. Each product  may  define
              different groups. Typical groups are: core, web, doc, test, etc.

       --show Show the actual commands executed by MakeMe.

       --static
              Configure to  build  using  static  linking  instead  of  shared
              libraries. Same as --set static=true.

       --unicode
              Set the character size to wide.

       --unset key=value
              Clear a settings property.  Use this when running 'me configure'
              to persist your changes in the configuration MakeMe file.

       --version
              Print the ejs command version and exit.

       --verbose
              Run in verbose mode with more trace about MakeMe activities.

       --watch msec
              Watch for changes and rebuild if required. This will  sleep  for
              the  requested  number  of  milliseconds  between  checking  for
              changes. This can also be invoked as 'me watch' which will check
              every second for changes.

       --why  Display why each target was or was not built.

       --with PACK[=path]
              Build  with  the named pack located at the optional path. If the
              path is ommitted, a search is performed for the pack at  default
              locations.  Packs  must  have  a pack description file installed
              under 'makeme/packs' in the MakeMe installation.

       --without PACK
              Build without the named pack.

REPORTING BUGS
       Report bugs to dev@embedthis.com.

COPYRIGHT
       Copyright (C) Embedthis Software. MakeMe and Ejscript are a  trademarks
       of Embedthis Software.

SEE ALSO
       pak

me                               January 2014                            ME(1)