Build instruction in main readme.md

[przem360]

🔧 Feature request 🔧

First of all - I love Alda and I just can't express how great this project is. I would like to thank the creators and everyone involved.

I just just would like to point out a minor documentation issue. I've found myself that running Alda requires studying the structure of this program, some aspects of this may be confusing, especially for a Raspberry Pi user who is unfamiliar with Kotlin and Go.

Description

I think that it may be useful to put simple build instructions in main readme.md file. It would be useful for people who use things like Raspberry Pi or maybe BSD systems.

Examples

1. Install OpenJDK, download Go for your system and install it.

2. Download and unzip Alda release or clone repository.

3. Compile player:

cd alda-release-X.X.X/player
./bin/run

Player binary is located in alda-release-X.X.X/player/target/X.X.X-/
4. Compile Alda client:

cd alda-release-X.X.X/client
go generate
go build

Client binary will be in alda-release-X.X.X/client

Motivation

There are musicians out there who are not familiar with Kotlin or Go but would be happy to test Alda.

Alternatives

Instructions are already in player/readme.md and client/readme.md so maybe it is just enough to link these files in main readme.md

[daveyarwood]

Hi @przem360 , thanks so much for the kind words!

I think adding links to the README in the client and player directories to the main README for manual build instructions is a good idea, for anyone who might be interested in building the project for specific use cases that we don't have releases for (Raspberry Pi, etc.)

(However, I'm also interested in providing releases for these other platforms, specifically Raspberry Pi! We've actually been talking a lot recently on the Alda Slack group about adding ARM binaries to the set of executables that we include in every release.)

[pkeir]

I found Alda after searching for something like it. It seems to be ideal, and clearly the best of its kind available. I would like to use it to notate music, before export to sheet music; at least sufficient to allow practise. I believe my route for this would be via midi export; before import to another program such as Musescore. Alas, I have lost track of an Alda blog/tutorial I had which explained the export to midi step.

Anyway, I am more familiar with C++ than Java/Clojure or Go. For security and longevity, I also prefer to build a project; and would ideally manually install dependencies myself before building. A month ago I tried to build Alda, with partial success. I too found it less than straightforward, and would agree that a markdown file in the project root covering this (e.g. BUILDING.md or README.md) would be most helpful. I say partial success, because I built the player, when actually for midi file creation, I now suspect it should be the client that I build? (Incidentally, if I should return to the player, I would like to have instructions on how to avoid using the Gradle wrapper script, as I prefer to install my own dependencies, or build from source.)

Congratulations on a fantastic project!

[daveyarwood]

Thanks @pkeir! :)

I would like to use it to notate music, before export to sheet music; at least sufficient to allow practise. I believe my route for this would be via midi export; before import to another program such as Musescore. Alas, I have lost track of an Alda blog/tutorial I had which explained the export to midi step.

I actually wrote this blog post recently, which wasn't exactly about MIDI export, but it was about MusicXML import and how it facilitates working in both Alda and other music notation software, which you might find helpful. There is an example where I used alda import to import a MusicXML file and output an Alda file, then I used alda export to produce a MIDI file, then I imported that MIDI file into MuseScore.

You can also check out alda import --help and alda export --help for more information and examples.

Anyway, I am more familiar with C++ than Java/Clojure or Go. For security and longevity, I also prefer to build a project; and would ideally manually install dependencies myself before building. A month ago I tried to build Alda, with partial success. I too found it less than straightforward, and would agree that a markdown file in the project root covering this (e.g. BUILDING.md or README.md) would be most helpful.

I totally agree that the documentation could be improved. There is already some information about how to get started in CONTRIBUTING.md -- in particular, the links to the READMEs for the client and player. I'm curious to know if you've seen those docs? If so, were they helpful, or was there additional context that you were missing? (And if not, how could we make them more visible?)

I say partial success, because I built the player, when actually for midi file creation, I now suspect it should be the client that I build?

It really depends on what you're trying to do. If your goal is to build Alda locally instead of installing an official release, then you do need to build both the client and the player and place them both in your PATH. If you haven't seen them already, check out the bin/build scripts in the client and player directories.

(Incidentally, if I should return to the player, I would like to have instructions on how to avoid using the Gradle wrapper script, as I prefer to install my own dependencies, or build from source.)

I don't understand this part. I thought the Gradle wrapper script was to allow people who don't have Gradle installed to build the project, as well as to ensure that the desired version of Gradle is used. If you have a suitable version of Gradle installed, I think you can just replace ./gradlew with gradle and it should work the same way. But I would recommend using the Gradle wrapper script, for the reasons I just mentioned.

[daveyarwood]

(Incidentally, if I should return to the player, I would like to have instructions on how to avoid using the Gradle wrapper script, as I prefer to install my own dependencies, or build from source.)

Wait, is your goal to build the player without using any dependency management tool? That would be very difficult, and I'm not sure how much help I could be there. But as a starting point, you could have a look at the build.gradle.kts file, which specifies which Java/Kotlin libraries Gradle should pull down from Maven Central, and what the gradle build task does (it builds a fat jar).

[pkeir]

Thankyou! The blog post is indeed the one I was looking for.

I'll look again at the CONTRIBUTING.md document. I may have missed it on my return to the project. I hope I can contribute in time, but for now I'm on the foothills.

Regarding dependency management: no, I am happy to use a dependency management tool (I use APT heartily); or build from source code. Your advice about changing ./gradlew to gradle sounds like exactly the solution I was after - I don't know anything about Gradle, but I'm happy to apt-get install gradle (and it seems I did do this a month ago). I avoid any other scripted downloading if possible.

Thanks again for your advice. Keep up the good work!