When an idea turns into a project, one of the steps is usually to check if there
is already an implementation about it, finding it will bring the excitement to
evaluate it. And probably one of the following case scenarios will occur:
You are happy with your findings, and you can use it as is.
You find something that is similar, and you would like to extend it.
You find something that might be the solution, but you don’t know how to try
it.
It’s too difficult, so you decide to start from scratch.
In any case, the project requires having a rough documentation, and you might
need to get into the details to give it a try.
Wouldn’t it be wonderful to have the same schema for any software project of
any kind?
The proposal is to have a common structure that allows a quickly immerse experience into the project.
What is the goal?
Use a generic project structure to allows users to quickly evaluate the solution
presented:
A POSIX compliant implementation.
Evaluate requirements to run the project, and provide actions to guide the
user, like an interactive readme.
If possible, containerize the implementation.
Define actions to start, stop and clean up the project.
Define common actions, or recommended use cases.
Define actions for CI that are independent of any automation software.
How to make it?
This title is a spoiler of the idea, use GNU Make.
Makefiles are powerful enough to provide a single entry point for any kind of
project. Using a Makefile to manage containers will add an extra layer of
abstraction and facilitate the adoption, at least in my perspective.
While a clean Makefile would be enough, I’ve come across with the project Docker compose makefile, which out of the box provides single line documentation
with a nice color organization.
The project has the following actions, along with some helpers for this library.
clean
dependencies
start
up
stop
status
restart
ps
help
In my view, to make this generic for any project and simplify the CI, it would
be good to have a:
test#And any other action that could be related to CI
deploy#Depending on the architecture
Emacs integration
Not too difficult to make it work from our beloved editor. helm-make is one of the options.
While I applaud the sentiment, there’s no one-size fits-all system. Especially not across programming languages. Why should Haskell users suddenly require make instead of cabal? Why would Rust users forgo cargo? Ruby devs gem? C++ users CMake+Ninja? Autotools users their selection of confusing tools, which (most often) have a handy INSTALL to alleviate said confusion?
Similarly, I can count many tools that wouldn’t make any sense within running container. Services? Sure. That’s helpful, and those projects typically include a docker run ... example within their README. But this already falls flat for embedded hardware projects that might not have an emulator.
General standardization seems therefore a bit much. Generating specific templates for some projects might be applicable.[1] And for many programming languages, there are already templates.
If your proposal was “Every project should have a README with the requirements and (tested) build steps”, then I’d say: “YES! ”. But adding yet another completely unrelated dependency (in your example docker and make) would make me drop that Rust library.
In my opinion: templates aren’t the issue. Subpar and outdated documentation is.
For example, having the same README style for all projects within a single GitHub organization. But still, many organizations have multi-language projects. ↩︎
Thanks for your feedback.
I understand your point, probably a standard is not the right word, in the end, nobody will enforce it.
The idea is not replacing anything, actually it’s more like an adapter pattern.
Taking the example of Haskell, you can still use cabal under the hood.
I thought about make just because I was guessing that it’s installed by default in most distributions.
The container was an example, thinking about microservice’s development, yet if the project at the front doesn’t consider one, then the straight command could be used. It could be anything, even the parameters that could be abstracted.
Maybe I’m doing too much context switch, and I want to avoid personal memory failures, so having make start reduces that iteration of thinking about which command I need to use to start this project.
With that logic, a run.sh would be more suitable, as /bin/sh (or at least a sh within $PATH) exists on all distributions. Whether it calls make internally would be another thing, but I could imagine that a run_alma.sh[1] with some kind of “common” interface could be helpful.
That would also be in line with your POSIX compatibility. You could work on a proof of concept there, that would be indeed interesting.
That’s exactly why I contribute to README and INSTALLS: if it takes me more than 10 minutes to get a running version, the next user should be able to do it quicker after my adjustments. Well, that’s at least what I hope.
Taken from your username. You could also call it alma.sh or project.sh, or some other fancy name. I haven’t had any coffee yet, sorry ↩︎
I’ve implemented some time ago the script approach, and the main thing that brought me back to make was the integration with the editor.
Using helm-make or helm-make-projectile provides the flexibility to trigger the desired action without having to jump to the path of the Makefile (if it exists on the root of the project).
Moreover, because Makefile is running a shell underneath, it felt like re-inventing the wheel.
That is great, I try to do the same, and by no means I’m trying to get rid of that discipline.
Allow me to explain more about the context switch. It’s not about the changes to the code that bother me. I’m thinking about those moments where we might need to jump from the editor to a terminal to run a well-defined command for the project. It could be typing the command on the terminal, or maybe just finding it in the history. Knowing that the same actions, could be just a couple of keystrokes away, from the editor, just with the effort of writing a minimal file like:
start:
npm run start:dev
Again, thanks for taking the time, and I’m excited to read if you have any other ideas on how to make the work to flow a little more.
Just to be sure: are we talking here about editors in general, or Emacs in specific? Because Emacs has the compile-command variable, which you can pre-set for projects via directory-local variables (see add-dir-local-variable). Together with compile-multi and its compile-multi-config, you should have a very flexible solution—that is, as long as this is actually meant as an extension of your Emacs workflow. Not sure whether that has a helm-* equivalent, I haven’t used helm in years .
I’m focusing on Emacs, but if the solution is helpful for other IDEs and also work on the shell, it would be great. After a brief look, I found that some of them have extensions to trigger the actions on the Makefile.
If I may turn your initial proposal on its head, if you’re looking to improve the integration with Emacs and are trying to make for a more consistent UI across projects, you could potentially look at something like handle:
I don’t know if it’ll fit your needs, you might just take inspiration from it, but it could potentially allow you to create consistent actions that abstract over the details of each language’s (or even project’s) actions.
I keep forgetting about compile-multi, it seems extremely useful. I use M-x compile for a lot of things so I imagine it’d be really useful for my tasks.
”. But adding yet another completely unrelated dependency (in your example 
