alanvgreen / lxbuildenv

Simplified environment for litex

lxbuildenv - Simple LiteX Build Environment

lxbuildenv is a Python module that takes care of setting up your build environment for LiteX. It is simple to use, cross-platform, and self-contained.

Usage - Initial Setup

ℹ️	The initial setup process is, admittedly, a little rough. Patches are welcome.

You can execute lxbuildenv.py directly. Run python lxbuildenv.py --init to create a new project. This will perform the following steps:

1. Ask you for a main entrypoint name, if --main was not set

2. Create a git repository, if one does not already exist, unless --no-git was set

3. Create a bin directory and populate it, if --no-bin was not set

4. Create an initial template program

From this point onwards, you do not need to invoke lxbuildenv.py. However, it must still be present in order for your program to run.

Usage - Running your Program

The purpose of lxbuildenv.py is to make it easier to get started on a project. It’s also designed to help you work on support libraries. It tries to use system dependencies whenever possible, including using system Python and system compilers.

As such, lxbuildenv.py does some tricky things with PYTHONPATH. It also re-executes itself to ensure PYTHONHASHSEED is set. Additionally, it ensures you have any dependencies installed already.

It does not download dependencies for you — for certain software that’s not even legally allowed. Instead it makes sure the software exists and is usable, and where to obtain it if it’s not available.

The lxbuildenv.py script adds several command line arguments to your program. These all begin with --lx-. To list all parameters provided by lxbuildenv.py, run --lx-help.

⚠️	Because it adjusts the import path, you must import lxbuildenv before you import any other packages.

Specifying Dependencies

Dependencies are specified by adding a variable in your main file called LX_DEPENDENCIES. The fact that this is a variable rather than some other method should set off alarm bells and tell you something funny is going on in lxbuildenv.py. This is true.

As part of its initialization, lxbuildenv.py will read in your program and look for this variable. It will then check any dependencies you’ve specified to ensure they are met, and may patch up the environment if necessary. For example, if you specify vivado as a dependency, lxbuildenv will make sure it can run the vivado program, and will add /opt/Xilinx/…​/ or C:\\Xilinx\... to the PATH as necessary.

To list all possible dependencies, run python lxbuildenv.py --lx-print-deps. If you want to try building something without having all the necessary dependencies, add --lx-ignore-deps to your build.

Usage - Tools

As part of its setup, lxbuildenv.py creates a bin/ directory. These are all very thin wrappers around existing tools. You can run these tools using python. For example, python bin/litex_server.