Streamline MMT setup for new developers

[katjabercic]

@lambdaTotoro @tkw1536 @Jazzpirate @ComFreek

There are currently lots of small things that can go wrong when new developers set up MMT.

In my observation, different things go wrong for different students, and if a single thing goes wrong, students are foten lost. Even worse, they start trying different things, which makes their setup un-debuggable, especially remotely.

Possible issues include:

• Writing or using archive-specific code requires setting up IntelliJ modules for MathHub repositories. These are outside the root directory of UniFormal/MMT and not guaranteed to be in the same location relative to UniFormal/MMT for every developer.
• IntelliJ's module files (*.iml) files are checked in but don't necessarily work for everybody.
• IntelliJ's project files (.idea folder) is not checked but could potentially be checked in partially. But then it would have to include some projects from MathHub archives as well.
• Modern versions of sbt do not always build MMT correctly even though the sbt specification says they should.
• @Jazzpirate reports IntelliJ sometimes overrides the sbt version in some global setting.
• sbt can generate IntelliJ module files, but those are not necessarily the ones we want. For example, I do not use them.
• Some people run sbt from within IntelliJ, possibly also using it to import the project in the first place. Others install sbt separately and run it on the command line.
• We cannot easily use sbt to build the code in MathHub archives because it sits outside the UniFormal/MMT root folder, and we do not have our own alternative solution.

We need to streamline this process with a single, simple setup that works for everybody.

Possibilities:

Use the same folder structure for MMT/UniFormal and MathHub for everybody. When installing MMT, this is currently

• UniFormal/MMT in ROOT/mmt-system/MMT/
• MathHub archives in ROOT/mmt-content/MathHub/GROUP/REPO Can this work for everybody?

Handcraft some files in .idea and all *.iml files using relative paths only and check those in. Then update the documentation to make new developers import an existing IntelliJ project.

[tkw1536]

See also: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839

[ComFreek]

Modern versions of sbt do not always build MMT correctly even though the sbt specification says they should.

I think we should fix this anyway regardless of any other issue raised here.

Some people run sbt from within IntelliJ, possibly also using it to import the project in the first place. Others install sbt separately and run it on the command line.

Also watch out that building in IntelliJ, building with SBT from within in IntelliJ, and building with SBT from command-line are three different things. (IntelliJ comes with bundled with an internal SBT installation)

If possible, I'd always avoid touching SBT on my own and just let IntelliJ do its import/building.

Re your suggested relative layout of MMT and archives:

• if I understand correctly, to use an archive, users still have to manually add the archive's module to their MMT IntelliJ project, right? What does this forced layout achieve then?
• I'd be okay with the forced layout in general, though, even if it makes things inflexible.

[florian-rabe]

Ideas from systems meeting today:

• Clean up sbt file
  • audit what it does, which includes at least
  • the sbt jedit/install target, which should be preserved or replaced with something else
  • targets for generating api documentation, which should be preserved
  • some stuff about testing
  • external Scala code in src/project, which can probably be removed (maybe move to mmt project as this code is only ever used after building the fat jar)
  • get rid of unimportant stuff, streamline
• Check if we can add a build-artifact setting to the sbt file that lets intelliJ build the fat jar
• Use the following instructions for new developers:
  • install intelliJ (give link to right version)
  • possibly: set some intelliJ settings
  • open sbt file
  • build mmt.jar artifact to produce fat jar
  • purge conflicting instructions from existing tutorials, documentation

[Jazzpirate]

Currently existing sbt tasks:

• deploy: Should use normal artifact/build stuff so that IntelliJ knows about it
• deployLFCatalog: "builds a stand-alone lfcatalog.jar" - do we still need it? (No idea what lfcatalog does, really)
• install: Should probably be replaced by a shell script or something?
• cleandoc: "remove api documentation." - do we still need that as an sbt task?
• apidoc: I'd guess we want to keep this?

[florian-rabe]

install: I think only jedit/install does anything, that's helpful but replacible

deployLFCatalog: not sure but probably not needed soon; at least preserve it as a commented out target

cleandoc: presumably needed in conjunction with apidoc

apidoc: might be work to redo differently; so probably has to be kept

[ComFreek]

For the record (already talked with @Jazzpirate), the SBT file has been previously adapted such that MMT can be pulled as an SBT dependency in other projects (e.g. FrameIT's server). Details can be found at my StackOverflow question for that.

I think we want to remain compatible with external projects depending on MMT.

[Jazzpirate]

It actually looks like there's no way to specify an artifact build in an sbt file such that IntelliJ adds it to its artifacts after importing... if anyone can find out something that would be great, but google seems to not yield any helpful results

[tkw1536]

Closest thing I'm aware is running an "sbt task" from within IntelliJ. But that does require some manual configuration, see https://stackoverflow.com/a/39408495/11451137.

[ComFreek]

IMO, #477 is on the critical path of streamlining, too. As of now, Windows users need to install Bash and put it on PATH to be able to use the MMT IntelliJ plugin.