.. _invocation_makefilegen.py

Invocation of makefilegen.py
============================

The :program:`makefilegen.py` script generates project Makefiles. Normally, it is invoked from Makefile.connectal and passed options via :make:var:`CONNECTALFLAGS`.

Project Options
---------------

.. option:: -B board, --board=board

   Specifies which board to build for. 

.. option:: --O os, --option=os

   Specifies which operating system to support. Usually derived from :option:board.

.. option:: --project-dir=dir

   Specifies the directory in which to creat the Makefile that
   performs the build. Creates the directory if it does not exist.

Source Options
--------------

.. option:: bsvfile

   This positional argument specifies which BSV files to parse for type and interface declarations.

.. option:: -s foo.cpp, --source=foo.cpp

   Specifies C and C++ files to include in the application.

.. option:: --ipdir=dir

   Specifies where to store IP cores generated by Vivado or Quartus

.. option:: --cachedir=dirname

   Specifies directory to be used by `buildcache`

.. option:: --nocache

   Disables `buildcache`

.. option:: -D var=value

   Binds var to value in software, BSV, Verilog, and Tcl contexts.

.. option:: -v, --verbose

   Verbose operation

Interface Options
-----------------

.. option:: --interfaces=...

   To be written...

.. option:: --dump_map

   Generate a JSON file describing the portals, for use in tracing tools such as `pcieflat`.

Software Options
----------------

.. option:: --cflags=flags

   Specifies build flags for the C/C++ compiler

.. option:: -I dir --cinclude=dir

.. option:: -l lib, --clib=lib

   Link the application with library lib.

.. option:: -S libfile, --clibfiles=libfile.a

   Link the application with library file `libfile.a`.

.. option:: -L libdir, --clibdir=libdir

   Addes `libdir` to the software library path.

.. option:: --nonstrict

   Pass --Wall to gcc instead of -Werror.

.. option:: --shared

   Specifies to build a shared library instead of an executable.

.. option:: --nohardware

   Suppresses build of hardware, for software-only projects.

.. option:: --stl=stltype

   Specifies which C++ Standard Template Library to use for Android. The choices are:

    * stlport_static: STLport runtime C++ exceptions and RTTI and Standard Template Library
    * stlport_shared
    * gnustl_static: GNU STL runtime C++ exceptions and RTTI and Standard Template Library
    * gnustl_shared
    * c++_static: LLVM libc++ runtime C++ exceptions and RTTI and Standard Template Library
    * c++_shared
    * gabi++_static: GAbi++ runtime C++ exceptions and RTTI
    * gabi++_shared

Hardware Options
----------------

.. option:: --bsvpath=dirname

   Adds `dirname` to the BSV module import path.

.. option:: -b options, --bscflags=options

   Flags to pass to the BSV compiler.


.. option:: -V file.v, --verilog=file.v

   Specifies verilog file to include in the design

.. option:: --pinfo=project.json

   This does what?

.. option:: --pinout=pinusage.json

   Specifies connection of pins on the board to top level signals of
   the design. A board-specific constraint file will be generated from
   pinusage.json and the boardinfo json file, and will be added to
   constraint and implconstraint.

   See :make:var::`PINOUT_FILE`, whose values are passed as --pinout options to makefilegen.

.. option:: --constraint=file.xdc

   Specifies synthesis phase constraint file.

.. option:: --implconstraint=file.xdc

   Specifies implementation (place and route) constraint file.

.. option:: --unmanaged-implconstraint=file.xdc

   Specifies unmanaged implementation (place and route) constraint file.
   This causes the xdc file to be read in using the `-unmanaged` flag of `read_xdc`.
   This allows the xdc files to use more tcl commands than a normal xdc file (including `if` and
   `foreach`).

.. option:: -P modulename, --partition=modulename

   Directs `fpgamake` to build a separate netlist for
   `modulename`. With `buildcache`, Reduces build times if module changes infrequently.

Xilinx Options
--------------

.. option:: --xci=core.xci

   Specifies IP core to include in the design. (Xilinx only)

Altera Options
--------------

.. option:: --qip=core.qip

   Specifies IP core to include in the design. (Altera only)

.. option:: --qsf=settings.qsf

   Specifies Altera Quartus settings.

Partial Reconfiguration Options
-------------------------------

.. option:: --prtop=mkTop.dcp

   Specifies filename of previously built top level.

.. option:: --prvariant=name

   ...

.. option:: --reconfig=modulenames

   ...

Bluesim Options
------------------

.. option:: -q, --qtused

   Link the bluesim `bsim` executable with libQt.

.. option:: -m foo.cpp, --bsimsource foo.cpp

   Specifies additional sources to compile into the `bsim`
   executable. If you are using Bluespec import "BDPI" or
   SystemVerilog "DPI"/"DPI-C", you will need to link additional
   sources into the simulator.

   Note: These files are currently compiled with g++, even if they are
   C files. You will need to use extern "C" to export symbols to the
   simulator.

Xsim Options
------------

.. option:: --xelabflags=flags

   Options to pass to `xelab`

.. option:: --xsimflags

  Options to pass to `xsim`


Clocking Options
----------------

.. option:: --mainclockperiod

   Specifies the period, in nanoseconds, of the main clock. Must be an integer.

   On Zynq boards, 

   On PCIe-connected boards, if the main clock period differs from the
   PCIe clock period, then the design's portals and DMA ports will
   automatically be connected via SyncFIFO's.

   Each boardinfo JSON file specifies the default value for mainclockperiod.

.. option:: --derivedclockperiod

   Connectal also makes a second clock available, host.derivedClock. The period of this clock is 

   Each boardinfo JSON file specifies the default value for mainclockperiod.