BuildPath.txt

Overview

The BuildPath.txt file is zamiaCAD's equivalent of a Makefile.

Create a file named BuildPath.txt inside your zamiaCAD project to

  • Include sources from outside your workspace (also called external sources)
  • Specify target library names
  • Specify file name patterns that are to be ignored
  • Specify toplevels

Example

This is an example of a BuildPath.txt file:

# All files matching "*.in.vhd*" will be ignored
ignore "*.in.vhd*"

# a local variable
LEON_SRC="$HOME/projects/workspace/zamia/examples/leonSOC"

# include an external BuildPath.txt
include "/projects/leon/BuildPath.txt"

# specify external sources and their target libs
extern GRLIB            "$LEON_SRC/lib/grlib"
extern TECHMAP          "$LEON_SRC/lib/techmap"

# external sources that are declared readonly will be cached on your local disk 
extern readonly SPW              "$LEON_SRC/lib/spw"

# specify target library for sources inside your workspace
local GAISLER "gaisler" 

# exclude a specific subdirectory
local none "gaisler/test"

# specify the default target library for local sources
# you can also use the keyword "NONE" here to exclude sources that
# reside in no sub directory

default none

# specify one or more toplevel(s) (each toplevel will be elaborated automatically)
# format: [ <LIBRARY> '.' ] <ENTITY [ '(' <ARCHITECTURE> ')' ]
toplevel WORK.LEON3MP(RTL)
toplevel LEON3S

Priorities: Order of BuildPath.txt entries is important

Each local or external entry has a priority assigned to it. The topmost entry has the highest priority which is then decreased for any entry that follows.

This is important if you have several files declaring the same library unit (entity, architecture, package, configuration, ...). In such a case, the unit with the highest priority wins, i.e. the unit that is found first while processing the build path and indexing your project.

Caching external files on local disk

Especially when your external source files are located on high-latency networked file systems (e.g. NFS/AFS mounts over high-latency connections) caching those source files on your local disk can help performance a lot.

You can instruct zamiaCAD to do exactly that by declaring external sources as readonly, e.g.

# external sources that are declared readonly will be cached on your local disk
extern readonly SPW              "$LEON_SRC/lib/spw"

will cause zamiaCAD to keep a local copy of all files found in $LEON_SRC/lib/spw on your local disk. The local disk cache resides in

/work/<login>/zamia/fs_cache

if /work exists on your machine, or in

/tmp/<login>/zamia/fs_cache

otherwise.

Updating the local disk cache

External sources declared readonly are not re-fetched from their original location during normal project build. You can however force zamiaCAD to re-fetch them by initiating a so-called explicit full build. To do that, select Clean... from the Project menu.

Handling filename conventions

zamiaCAD knows a special IBM-Mode which essentially means that files that will be compiled into your WORK library will be handled in portal's "top-down" style approach: they will only be considered if their file names match the names of the contained architectures and entities, otherwise ignored. Libraries that are not called WORK will not be treated this way.

To activate the IBM-Mode, add the following directive to the top of your BuildPath.txt:

option "IBM" true

Alternatively and/or additionally, you can specify the file-name policy per build path entry:

# files in /home/bar/mychip not following the IBM filename-convention will be ignored:
extern topdown FOO "/home/bar/mychip"

# files in /home/bar/work not following the convention will be regarded:
extern bottomup WORK "/home/bar/work"

Variables

   <varId> '=' <string>

All variables have the type string and don't have to be declared (dynamic), you simply assign them and they come into existence. Assigning the same variable again will replace the variable's contents. Variable contents can be accessed in any string following the first assignment using the $ character, e.g.

   foo = "bar"
   foo2 = "contents of foo: $foo"

Command Reference

Default

   'default' ( <string> | 'none' )

Specifies the default target library for local sources. Any source file found in the project directory (project workspace if you're using the Eclipse plugin) will end up in the library specified here or will be ignored if 'none' is specified here. WORK is the default target library.

One application of the default declaration is having a separate source folder in your project, e.g.

   default none
   local "WORK" "src"

Exec

   'exec' <filename>

Execute the specified Python script on project initialization and before any clean rebuild. Can be used to declare project-specific custom Python commands before the build, e.g. to run external HDL tools by providing zamiaCompile and zamiaElaborate commands. See External HDL Tool Support for details.

Example:

   exec "builtin:/python/boot.py"

Extern

   'extern' ['readonly'] [ 'topdown' | 'bottomup' ] [ 'recursive' | 'nonrecursive' ] ['list'] (
<libId> | 'none' ) <pathPrefix>

Specify additional source directories to be indexed (and on-demand compiled) outside the local project directory.

Options:

  • readonly: Aggresive caching on local disk (will fetch contents only once at initial index run and on user-triggered full builds)
  • topdown, bottomup: IBM-specific file name conventions (see above).
  • list: the path specified is not a directory but an ASCII file containing a list of files to be compiled (please note: if entry is marked as readonly, list contents AND contents of the files in the list will be cached)
  • recursive, nonrecursive: Default is recursive. Specify nonrecursive to prevent builder from recursing into the directory.

If the keyword none is used instead of a library identifier, the contents of this directory will be ignored (useful for nested external directories).

Ignore

   'ignore' <pattern>

File names that match the given (glob-style) pattern will be ignored, e.g.

   ignore "*.vhdl.inc"

Include

   'include' <path>

Includes another BuildPath.txt-style file. Example:

   include "/data/prjA/commonBP.txt"

Local

  'local' [ 'topdown' | 'bottomup' ] ['list'] (<libId> | 'none') pathPrefix

Specifies a target library for local source files.

Options:

  • topdown, bottomup: IBM-specific file name conventions (see above).
  • list: the path specified is not a directory but an ASCII file containing a list of files to be compiled

If the keyword none is used instead of a library identifier, the contents of this directory will be ignored.

Option

  'option' <string> ( <bool> | <string> )

Specifies a zamiaCAD option. Currently only one option is defined:

  • IBM: if set to true, special IBM-style filename conventions apply (see above)

Toplevel

   'toplevel' [ <libId> '.' ] <entityId> [ '(' <archId> ')' ]

Specifies a toplevel to be elaborated. Examples:

   toplevel MYENTITY
   toplevel WORK.ANOTHERENTITY
   toplevel WORK.THIRDENTITY(ANARCHITECTURE)

Theme by Danetsoft and Danang Probo Sayekti inspired by Maksimer