Document FUSESOC_CORES environment variable

[imphil]

The documentation at https://fusesoc.readthedocs.io/en/master/user/overview.html#core-search-order doesn't mention the FUSESOC_CORES environment variable, or how it relates to the search order.

[olofk]

My preference would actually be to drop it and tell people to use --cores-root instead, but I might be missing some use case.

[imphil]

We use FUSESOC_CORES in OpTiMSoC to enable users to source a single file (source optimsoc-env.sh) and then just run FuseSoC without passing a specific cores root to each invocation. We probably need to think about how strong we want to make the support for "cores roots" compared to always using libraries, and just add enough functionality there to enable such uses as we have in OpTiMSoC.

[olofk]

I uses --cores-root all the time when I need to e.g. temporarily use a different version of a core.I would be very sad if that option disappeared. And it's pretty much the same thing as OpTiMSoC does but through a env var instead. I prefer --cores-root because I think it's more discoverable through fusesoc --help FUSESOC_CORES is also the only env var we have which makes it a bit of a special case. Also not sure if fanyone outside of OpTiMSoC uses it. At the same time, it's not a good idea to remove it if serves a purpose and is in use. But please look at the alternatives. The main ones I guess would be to provide a preconfigured fusesoc.conf, run fusesoc library add (unless already done) when the optimsoc-env.sh is sourced or go with --cores-root instead

[sjalloq]

I just wanted to add my voice to keeping FUSESOC_CORES. I've always used it to set the root for projects from with some sort of common sourceme. It also saves typing and I don't have to think about where I am in the hierarchy in order to specify the correct path to --cores-root. It also helps with new users who aren't that familiar.