MacOS install scripts by Ludblanc · Pull Request #889 · x-heep/x-heep

Ludblanc · 2026-02-19T09:48:05Z

Here I propose 2 scripts:

util/install_tools_and_conda_env.zsh allow to install the tools with specific versions and fix some compatibility issues such as pyYAML, and compilation issues with the specific version of verilator required for x-heep.

util/start_env.zsh is a script to source to start the environment.

The two scripts works on both macOS arm64 and intel, as well as intel ubuntu.

Incidentally the python version had to be updated for compatibility issues.

I tried to update the documentation accordingly

…start the env

LuigiGiuffrida98 · 2026-02-19T13:25:36Z

Hi @Ludblanc,

I tested it on my MacBook Air M4, I got this error:

Build complete!

Now type 'make test' to test.

-------------------------------------------------------
Setup Complete!
To activate: source util/start_env_macos.zsh
-------------------------------------------------------
❯ source util/start_env_macos.zsh
✅ CORE-V Mini-MCU environment activated.
❯ make test
$You are executing from: /Users/gigi/workspace/x-heep/x-heep
USING MINICONDA core-v-mini-mcu
make mcu-gen X_HEEP_CFG=configs/ci.hjson
$You are executing from: /Users/gigi/workspace/x-heep/x-heep
USING MINICONDA core-v-mini-mcu
/Users/gigi/miniconda3/envs/core-v-mini-mcu/bin/python util/mcu_gen.py --config configs/ci.hjson --python_config  --pads_cfg configs/pad_cfg.py --outtpl "./sw/linker/link_flash_exec.ld.tpl ./sw/linker/link.ld.tpl ./sw/linker/link_flash_load.ld.tpl ./sw/device/lib/drivers/power_manager/power_manager.h.tpl ./sw/device/lib/runtime/core_v_mini_mcu.h.tpl ./sw/device/lib/runtime/core_v_mini_mcu_memory.h.tpl ./sw/device/lib/crt/crt0.S.tpl ./hw/core-v-mini-mcu/system_bus.sv.tpl ./hw/core-v-mini-mcu/spi_subsystem.sv.tpl ./hw/core-v-mini-mcu/ao_peripheral_subsystem.sv.tpl ./hw/core-v-mini-mcu/peripheral_subsystem.sv.tpl ./hw/core-v-mini-mcu/cpu_subsystem.sv.tpl ./hw/core-v-mini-mcu/include/core_v_mini_mcu_pkg.sv.tpl ./hw/core-v-mini-mcu/core_v_mini_mcu.sv.tpl ./hw/core-v-mini-mcu/system_xbar.sv.tpl ./hw/core-v-mini-mcu/memory_subsystem.sv.tpl ./hw/system/x_heep_system.sv.tpl ./hw/system/pad_ring.sv.tpl ./hw/system/pad_control/rtl/pad_control.sv.tpl ./hw/system/pad_control/data/pad_control.hjson.tpl ./hw/fpga/sram_wrapper.sv.tpl ./hw/fpga/scripts/generate_sram.tcl.tpl ./hw/ip/power_manager/rtl/power_manager.sv.tpl ./hw/ip/power_manager/data/power_manager.hjson.tpl ./hw/ip/soc_ctrl/data/soc_ctrl.hjson.tpl ./hw/ip/dma/data/dma_conf.svh.tpl ./hw/ip/dma/data/dma.hjson.tpl ./hw/ip/pdm2pcm/rtl/pdm_core.sv.tpl ./hw/ip/pdm2pcm/rtl/pdm2pcm.sv.tpl ./hw/ip/pdm2pcm/data/pdm2pcm.hjson.tpl ./tb/testharness.sv.tpl ./tb/testharness_pkg.sv.tpl ./tb/tb_util.svh.tpl ./scripts/pnr/core-v-mini-mcu.upf.tpl ./scripts/pnr/core-v-mini-mcu.dc.upf.tpl" --externaltpl "" --cpu  --bus  --memorybanks  --memorybanks_il  --external_domains
Traceback (most recent call last):
  File "util/mcu_gen.py", line 10, in <module>
    import hjson
ModuleNotFoundError: No module named 'hjson'
make[1]: *** [mcu-gen] Error 1
make: *** [test] Error 2

Ludblanc · 2026-02-19T13:35:41Z

Hi @LuigiGiuffrida98 ! Do you have any error message during the conda environment generation during the script?
Or did you already had a conda env with this exact name before?

and make test you see is from the verilator build not from x-heep. It seems that make test in xheep is for ci integration and use hardcoded prefix for riscv compiler which will anyway make it fail (as our compiler on mac is called riscv32-corev-elf and not riscv32-unknown-elf-gcc. how ever if you use the normal make mcu-gen, make app, make verilator-build, make verilator-run this should work once the conda env issue is solved.

LuigiGiuffrida98 · 2026-02-19T13:45:44Z

I completely uninstalled conda (removing the environment too), verilator and the toolchain to restart from scratch. I reinstalled conda and run your script.

hjson and some other packages are installed as a dependency of fusesoc/edalize. But pylibfst installation fails because of cmake versioning errors. The workaround is to use a specific version of python instead of letting conda inherit it from the system (python 3.8 should be fine) python >= 3.10 deprecates the support for the version of cmake required by the version of pylibfst installed by edalize.

(This is the issues I encountered when installing the conda env on my mac and the workaround I used to fix things).

I will try it asap and push the fix to this branch

Ludblanc · 2026-02-19T13:47:50Z

and make test message you see is from the verilator build not from x-heep. It seems that make test in xheep is for ci integration and uses hardcoded prefix for riscv compiler which will anyway make it fail (as our compiler on mac is called riscv32-corev-elf and not riscv32-unknown-elf-gcc. how ever if you use the normal make mcu-gen, make app, make verilator-build, make verilator-run this should work once the conda env issue is solved.

Ludblanc · 2026-02-19T13:48:46Z

you can also set this env variable: CMAKE_POLICY_VERSION_MINIMUM=3.5

davidmallasen

@davideschiavone @StMiky what do you think of adding these scripts to the repo? I'm not entirely convinced as could be an unreliable shortcut in different systems, but on the other hand could be handy

davidmallasen · 2026-02-27T14:40:30Z

  - conda-forge
 dependencies:
-  - python=3.8
+  - python=3.11


We are planning to update to python 3.12 as discussed in #891 and #879, so I would keep that update separate from here. This includes the update setuptools that you also added here

davidmallasen · 2026-02-27T14:43:23Z


 Links for the packages relative to each software can also be found under the corresponding section of this guide. In general, make sure to have a look at the [Check system requirements](https://opentitan.org/book/doc/getting_started/index.html) section of the OpenTitan documentation.

+The script `util/install_tools_and_conda_env.sh` can be used to install the required dependencies and set up the Conda environment on Linux. It uses `apt` to install the required packages and then sets up a Conda environment with the necessary Python dependencies. It also installs the CORE-V toolchain, Verilator and the oss-cad-suite. You can select the versions of the tools you want to install by changing the corresponding variables at the beginning of the script. After running the script, you can activate the environment with `source util/start_env.sh`.


Where are these .sh versions? I only see .zsh.

davidmallasen · 2026-02-27T14:44:27Z

+# --- Configuration & Versions ---
+RISCV_V_DATE="20240530"
+OSS_CAD_DATE="2026-02-15"
+VERIBLE_HASH="v0.0-4051-g9fdb4057"


This is not the version we have in the documentation. It should be v0.0-4023-gc1271a00

davidmallasen · 2026-02-27T14:51:16Z

-  - python=3.8
+  - python=3.11
  - pip
+  - pyYAML


We should add a version if we move it from the requirements to here

davidmallasen · 2026-02-27T14:54:16Z


 Links for the packages relative to each software can also be found under the corresponding section of this guide. In general, make sure to have a look at the [Check system requirements](https://opentitan.org/book/doc/getting_started/index.html) section of the OpenTitan documentation.

+The script `util/install_tools_and_conda_env.sh` can be used to install the required dependencies and set up the Conda environment on Linux. It uses `apt` to install the required packages and then sets up a Conda environment with the necessary Python dependencies. It also installs the CORE-V toolchain, Verilator and the oss-cad-suite. You can select the versions of the tools you want to install by changing the corresponding variables at the beginning of the script. After running the script, you can activate the environment with `source util/start_env.sh`.


Clarify that this is only a shortcut that should be understood rather that run blindly. For both this and macos

LuigiGiuffrida98 · 2026-05-20T10:03:35Z

Hi @Ludblanc what is the status of this PR?

Ludblanc · 2026-05-20T12:00:25Z

Hi @LuigiGiuffrida98,
Just for context: I've been using x-heep as a hobby project for 2 weeks in March, not as part of my PhD. I'll have more time to contribute after my next tapeout.
The motivation for this PR is that I installed it this way on my machine while supervising a student who is trying to compile x-heep for Lattice FPGA, and I thought it could be useful for other people using Macs.
A couple of notes based on @davidmallasen's feedback: the Python version was picked because with 3.8 the conda env couldn't be created on macOS, and the config targets zsh since it's the default shell on Mac.
If anything isn't working or needs small adjustments, I'm happy to take care of it.

Ludblanc added 2 commits February 19, 2026 10:37

[macos utils] add script to install basic toolchanin on macos and to …

0df47f5

…start the env

[macos utils] add documentation about the macos install scripts

5447951

davidmallasen requested a review from LuigiGiuffrida98 February 19, 2026 10:21

LuigiGiuffrida98 and others added 7 commits February 23, 2026 17:41

port to macos intel and ubuntu

de8348d

Merge branch 'main' into main

52afbbe

fix for ubuntu

f3ef3de

remove the tools folder from git

ed8e9ff

Fix path issues

dfe4bb0

Add correct url for intel macos

1e27cf8

add x-heep contributors

fae8f04

LuigiGiuffrida98 approved these changes Feb 24, 2026

View reviewed changes

LuigiGiuffrida98 requested a review from davidmallasen February 24, 2026 10:57

davidmallasen requested changes Feb 27, 2026

View reviewed changes

LuigiGiuffrida98 added documentation Improvements or additions to documentation tooling Tool related edits labels Mar 17, 2026

LuigiGiuffrida98 self-requested a review May 13, 2026 09:00


		Links for the packages relative to each software can also be found under the corresponding section of this guide. In general, make sure to have a look at the [Check system requirements](https://opentitan.org/book/doc/getting_started/index.html) section of the OpenTitan documentation.

		The script `util/install_tools_and_conda_env.sh` can be used to install the required dependencies and set up the Conda environment on Linux. It uses `apt` to install the required packages and then sets up a Conda environment with the necessary Python dependencies. It also installs the CORE-V toolchain, Verilator and the oss-cad-suite. You can select the versions of the tools you want to install by changing the corresponding variables at the beginning of the script. After running the script, you can activate the environment with `source util/start_env.sh`.

Conversation

Ludblanc commented Feb 19, 2026 • edited by LuigiGiuffrida98 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LuigiGiuffrida98 commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ludblanc commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

LuigiGiuffrida98 commented Feb 19, 2026

Uh oh!

Ludblanc commented Feb 19, 2026

Uh oh!

Ludblanc commented Feb 19, 2026

Uh oh!

davidmallasen left a comment

Choose a reason for hiding this comment

Uh oh!

davidmallasen Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

davidmallasen Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

davidmallasen Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

davidmallasen Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

davidmallasen Feb 27, 2026

Choose a reason for hiding this comment

Uh oh!

LuigiGiuffrida98 commented May 20, 2026

Uh oh!

Ludblanc commented May 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Ludblanc commented Feb 19, 2026 •

edited by LuigiGiuffrida98

Loading

LuigiGiuffrida98 commented Feb 19, 2026 •

edited

Loading

Ludblanc commented Feb 19, 2026 •

edited

Loading