Compilation instructions for languages that require it

[leios]

Feature Request

Description

It would be a good idea to have compilation instructions available for languages that require them. For example, C / C++ could have a makefile and rust could have a cargo.toml file available. I had some trouble getting the #686 working, and this might help.

There are a large number of existing implementations that could benefit from this.

For Algorithm Archive Developers

• [ ] This feature can be added to the Master Overview (if it cannot be, explain why in a comment below -- lack of technical expertise, not relevant to the scope of this project, too ambitious)
• [ ] There is a timeline for when this feature can be implemented
• [ ] The feature has been added to the Master Overview
• [ ] The feature has been implemented (Please link the PR)

[leios]

myusernamefrank from twitch chat said:

sometimes other books or tutorials have a general build environment for all examples, maybe might be a good idea if it is one big project for each language which can be just compiled and generates all binaries?

[jiegillet]

I'm with myusernamefrank, one example should do it, something trivial in the code itself (hello world) but non-trivial in the structure ( import a few libraries...).

[leios]

So to be clear: You guys would prefer a single chapter on compilation where we explain the process for each language used in the AAA?

I think this is a good idea and would save some headache in the future. I don't know if we also need local build configuration as well?

[jdonszelmann]

Instructions globally are fine, but we need some part of it locally as well. For example, some of the code in the archive uses libraries (such as for Rust: generating random numbers). It's useful to have some instructions on which libraries to load locally. In the case of rust, this is a Cargo.toml file (and a small project structure). In the case of c, maybe a makefile? For Javascript maybe a package.json etc.

[leios]

Including the Cargo.toml file, Julia files should probably all have a Project / Manifest available so users can load everything with just julia --project

[ShadowMitia]

Maybe for C/C++ we could have some script files? A combination of "build.sh" and "build.bat", to make it easily cross platform, and not have to depend on too many third parties? Makefiles don't work out of the box on Windows, and things like CMake are a pain to setup and manage.

This could apply to other languages as well, but in C/C++ it would be a good practice to encourage enabling more warnings, to detect more bugs.

For example in C++ I use all of these:

-Wall -Wextra -Wshadow -Wnon-virtual-dtor -Wold-style-cast -Wcast-align -Wunused -Woverloaded-virtual -Wpedantic -Wconversion -Wsign-conversion -Wnull-dereference -Wdouble-promotion -Wformat=2

[Amaras]

Talking about Make and CMake, maybe we could use SCons. (I'll add the link once I'm on my PC again) I'm not entirely sure it is completely cross-platform in all cases, but I think it's close enough in all the common cases, which is what the AAA mostly needs.

I agree with the additional warnings, in any case.

[leios]

I would lean towards Make and CMake because it's what I know; however, I also agree that they might not be the right tools for this job. Why is CMake hard to set up? Isn't it just install and go?

If everyone prefers SCons, I am happy to use that as well!

[ShadowMitia]

I guess it depends at what level everything is used. CMake is kinda verbose, so for small projects it's a bit annoying to use. But in this case it's probably worth it, and would be easily cross-platform.

I use this repo as a reference for CMake https://github.com/lefticus/cpp_starter_project,

It's got a CMakeLists.txt and then inside the cmake folder, there are more files to help manage CMake. For a 50 line project, it feels very overkill :joy: But I also like being minimalistic (and perhaps too much). Not everything needs to be kept, but something simpler would be better I think.

Although now that I think about it, providing project templates could be a way to manage this.

[Amaras]

I don't know CMake at all, so I'm not able to provide some perspective on it. I know SCons was developed as an alternative to the Make/CMake combo, so that's something to take into account.

Of course, requiring a Makefile or CMake file could create a barrier of entry for beginner, which I think SCons could (maybe) attenuate, assuming we provide sufficient infrastructure to support this (and CMake has the same problem, of course).

[leios]

Yeah, this is the problem with C++. There are no standards. Let me see if I can write up a MakeFile, CMakeLists.txt, and whatever Scons uses for a simple project to compare

[leios]

For now, since we do not have a set plan, I will go ahead and merge C/C++ code. But we will come back to add it in later!

[mika314]

We have plenty of languages and essentially if someone wants to try some language they have to install and configure the language; also install dependencies; also, we have to take into consideration different OSes.

Here is an idea. Use a docker. Docker solves all of these problems. We can just provide a docker file with all dependencies resolved. We can have one set of instructions: basically how to install, configure and run docker.

Docker runs on Linux, Windows, and Mac. It does not take too much space in the GIT repo, it is just a text file Dockerfile.

Reviewers can easily review languages they are not familiar with, they will not need to install language on the host machine. They can run the program in the docker and review the output.

We can install into the docker as many dependencies as we want: CMake, make, CSons, premake...

We can also set up CI to automatically run tests on PR.

We can put the book generation and serve in the docker as well.

[ntindle]

likewise for C# project files

[berquist]

Here is a table to keep track of all the languages that currently have implementations, what tool they'll use for the build system, what additional files need to be added, and what interpreter/compiler they'll be calling. Please modify it as you see fit.

language	tool(s)?	file(s)	implementation(s)?
Assembly (x86)
Bash
C			gcc/clang?
C++			g++/clang?
C#
Clojure
Coconut			coconut
Common Lisp
D
Elm
Emojicode
Factor
Fortran (90)			gfortran
Go
Gnuplot
Haskell
Java
JavaScript
Julia
Kotlin
LOLCODE
Lua
Matlab/Octave
Nim
OCaml
PHP
Piet
PowerShell
Prolog
Python			CPython
R
Racket
Ruby
Rust	Cargo	Cargo.toml	rustc
Scala
Scheme
Scratch
Swift
V
VimL
Whitespace

[Amaras]

Yeah, this is the problem with C++. There are no standards. Let me see if I can write up a MakeFile, CMakeLists.txt, and whatever Scons uses for a simple project to compare

@leios Have you had the time to do what you said? I made PR #863 to show an example structure for SCons instructions.

[ntindle]

Take a look at my draft #862 to see a lot of the implementations

[Amaras]

Take a look at my draft #862 to see a lot of the implementations

By the way, if we go with SCons, you'd need to add pip install scons to your Dockerfile.

[Amaras]

As apparently we are using SCons as a basis (see this message and the next one for those on the AAA Discord server), a few options come to mind.

First, there is the possibility of providing algorithm-by-algorithm SConstruct files, which provide compilation instructions for each language, and even a way to run programs which produce an output file (see PR #863 for that, but it's still a WIP). It's quite easy to do, but it asks for some copy-pasting, which is annoying, and the compilation instructions are not that straight-forward for some languages, so we would need to provide a library that defines Builder objects that are importable individually. However, that gives the possibility of running the algorithm directly and redirect stdout to a file (say by running scons stdout.txt or something like that), which would help with automated verification efforts for issue #824 by providing a unified way to run the algorithms.

One other way would be to provide several language targets (not sure exactly how to do it for whole directories, but I'm sure it's possible), and build each algorithm (just copy files for languages like Python) in the correct folder. This one demands more work, but seems easier to deal with, because we can just create Builder objects at the root and just propagate them down the hierarchy. That would make things easier for contributors (simply provide an SConscript file which imports all the variables and uses the Builder objects we provide), compared to the approach cited above. However, the main downside is that it would not help with the automated verification efforts, in the sense that it would compile all the algorithms in one language.

Of course, there is always the option of doing both (providing both SConscript and SConstruct files), which is… okay, I guess? I'm not going to lie, this is not my favourite way of handling the situation, but it gives users the choice.

So, what do you guys think?

[leios]

I think having several language targets makes the most sense here and would be happy to see things move in that direction, but I think we need @stormofice to chime in here.

[Amaras]

So the main point with that approach would be that we would have to have a build directory where all compiled binaries (or copied files for interpreted languages) would be inside their respective language folders, and algorithms subfolders (or maybe we could drop the subfolders). To run them, users would need to go to the respective folders, and run the binaries (we should probably make sure that there are shebangs in the files for interpreted languages and make them executable) with ./filename.

With the Docker container, we can ensure Ubuntu 20.04 behaviour, so I don't think we have a problem with that. It will take some time to implement, though, as I'm not really familiar enough with SCons Builder objects yet.

I'll also close #863 because it's not relevant any more.