Guide for AwesomeWM Development Environment

[raven2cz]

AwesomeWM DevEnv

Basic user configurations, simple wibars, layouts, basic themes don't need libs import and looking to the libraries of AW project. It is possible to use with the AW API and its documentation.

However, this will quickly change if you need to start doing more complex things and components. When using Lua components, it is often necessary to look at implementations and cooperation already written in the AW library.

Furthermore, there may be a large group of people who can begin to contribute to AW fixes and enhancements; so that stable versions have a shorter release cycle again.

I don't think I'll be alone who lacks simple tutorials on how to run a "quality" environment for AW development; source code and AW debugging are available throughout the project, as used by contributors to this project.

Furthermore, I think that this will also help to unify the use of some of the tools that are needed for this.

So is it possible for experienced contributors to create a quality guide for setting up a development environment to contribute to a project and include it on the main AW pages? This can open the door to the points which are already described.

[basaran]

Depends on what kind of dev environment you are referring to. Awesomewm has got two sides, there is the LUA code and the C code. When you compile the source, it compiles the C code that handles the interaction between awesomewm and X11, and it will also give you the standard Lua libraries we are using such as awful, naughty, wibar and so on.

The API documentation we are all reading is mostly the Lua libraries. If you would like to ease your Lua development, Xephyr appears to be the common utility, which will give you an X11 instance to do as you please.

There is some documentation available as well:

https://awesomewm.org/apidoc/documentation/10-building-and-testing.md.html
https://awesomewm.org/doc/api/documentation/17-porting-tips.md.html

and there is a known problem with the API docs right now, some links are broken from google results. awesomeWM/awesome#3393

You can look into this repository for an awesomewm xephyr configuration tool:

https://github.com/serialoverflow/awmtt

I think we do need a new website for the API docs, and if I recall correct, there was already a candidate working on it but not sure if it went the right direction.

[raven2cz]

Thanks, I already found 10-building-and-testing.md.html. It is very important page. And building works correctly according actual information.

I combine my project structure with awesome-git project in CLion, install

• EmmyLua plugin,
• luacheck,
• set awesome-git as library project in the configuration of lua plugin

works great.

[raven2cz]

The issue was not about testing with Xephyr. It is already documented in many pages, forums etc.
There is missing configuration and settings of IDE, or other tools for debug processing.
This issue is about these problems. Not user simple configuration of rc.lua etc.
I close this issue, but it is still visible that this information missing.

[Aire-One]

Long story short : there is no "standard" tools to use with awesome development. As long as the Travis CI pipeline passes, we don't really care what tool you used or how you wrote the code.

You can use in your local machine, the same tools we use in Travis. It'll help you to check your code locally before sending a PR. Regarding the coding style, we have this short (and basic, I'd say) .editorconfig and vim modline in (almost?) every file. You can also install and configure luacheck to use our .luacheckrc. To do things correctly, it's also recommended (but not mandatory) to run the tests (make check or it's "sub-targets") to check you didn't break something with your changes.

For a long time, I personally was running the Atom editor with a lot of plugins (syntaxe highlighting/check, luacheck, Lua snippet, git blame, vim mode...) and run build, test and Xephyr from the terminal.
From what I can see, we have a lot of users that use VSCode now. IIRC, most of the "old school" users use vim or neovim.

I combine my project structure with awesome-git project in CLion, install

• EmmyLua plugin,
• luacheck,
• set awesome-git as library project in the configuration of lua plugin

works great.

Yeah, that work too. From my experience, it's not optimal since the EmmyLua plugin bases its intellisence on a different notation than ldoc (which is what we use for our in-code documentation).

Regarding debug, I have recently tested https://github.com/slembcke/debugger.lua. It seems to work pretty nicely. Maybe an IDE like intellij have plugins that work with graphical mode?

I have re-opened the issue to allow the discussion to goes on. I don't think it will produce a magical solution for everyone, but maybe someone will come up with interesting ideas (?)...

[basaran]

I think a website to organize all the information on reddit and github would be helpful. That way people can send updates as PRs. A static site generator from markdown might work.

[actionless]

@basaran like this one, for example? https://github.com/awesomeWM/awesome-www/

[basaran]

@actionless yes :)

I was thinking with a website redesign as well, something like those new js framework documentation sites, perhaps it would be better to move to a js framework with static site generation?

https://svelte.dev/docs

I like this one.

[actionless]

new js framework

not gonna happen though

[basaran]

We can still keep the current stack, just change the layout?

[basaran]

It could look something like this (just patched in the vuedocs):

[actionless]

We can still keep the current stack, just change the layout?

yes, PRs (with screenshots, please) are welcome, our previous design was submitted about 5 years ago, so i think people would be quite open to some improvements

Might be a good opportunity to give GitHub's Discussions feature a spin (there should be a way to convert an issue).

yes, also good idea

[raven2cz]

If you ask users why arch linux is successful, we often get the answer that they have good documentation.

It's similar with Awesome, it also tells you that the API is documented. But this is not just about the description of the API, which is very similar to javadoc, which "unfortunately" is no longer popular.

If you return back to arch documentation, it's always domain-based, followed by an important description of the domain, but after that follow very great examples of usecases and then troubleshooting, where a lot of sauce is added from users.
This is the way to the success of good documentation, and frankly, almost no one else uses it that way, and it's a great pity.

These pages from basaran look very great and if it would lead to the description I wrote, it is a clear win that will attract many users and newbies.

[hewcaw]

Might be a good opportunity to give GitHub's Discussions feature a spin (there should be a way to convert an issue).

Yes please enable it, I don't know how to use IIRC and the Sub Reddit seems a little bit bloating though.

It could look something like this (just patched in the vuedocs)

@basaran, do you have any plan on this? I would like to contribute some though, Svelte is definitely a great choice and I want a more beginner-friendly website that guides us from the basic stuff (guides, tutorials) to more advance stuff (docs, etc).

[sclu1034]

Svelte is definitely a great choice

I'm sure Svelte is a great piece of technology. But throwing a full-fledged application framework at a set of static pages is like buying a forklift to carry a six-pack of beer.

The current Markdown -> HTML conversion is good enough (although I'm not sure about what's going on with the spam commits at ikiwiki).
If anything, a reasonably featureful template engine (Tera, Pug, Jinja2, Go templates) would allow for more flexibility in individual page design, while still generating static pages to host on GitHub Pages and keeping content editing for the handful of pages manageable.

a more beginner-friendly website that guides us from the basic stuff [...] to more advance stuff

That's determined by content, which can already be added now. It does have to be written, though, and wouldn't just appear out of nowhere in a visual re-design.

[basaran]

Current stack is just fine. I was just referring to design elements and the appearance of content mainly. I agree there is no need to change the current website backend.

[sclu1034]

there is no need to change the current website backend

Actually, I'm not sure about that.

It's good enough for the current design. But if you want to implement an even slightly more complex landing page, like the mockup you showed previously, it would probably get in your way.
Markdown doesn't really lend itself to stuff like "put these three containers in a horizontal flex" or "alternate between text left, image right and image left, text right", since it's all just flat sequence of <p>s.

Unless you intend to add a ton of :nth() CSS selectors or embed HTML into Markdown. And releases.mdwn already looks only barely editable due to the weird table syntax.

[Thomashighbaugh]

I'm sure Svelte is a great piece of technology. But throwing a full-fledged application framework at a set of static pages is like buying a forklift to carry a six-pack of beer.

A little dismissive don't you think? And hyperbolic, but not the point I am ever trying to make.

It's good enough for the current design. But if you want to implement an even
slightly more complex landing page, like the mockup you showed previously, it
would probably get in your way.
Markdown doesn't really lend itself to stuff like "put these three containers in a
horizontal flex" or "alternate between text left, image right and image left, text
right", since it's all just flat sequence of

s.

Ummmmmmm, yeah you can do that with Markdown, you just write it in HTML within the markdown file and your rendering platform will 99% handle this just fine, because remember Markdown is just simplified HTML that's being rendered into normal HTML.

Proof?

• page with three columns
• Markdown file it is rendered from that is using HTML (you will have to hit edit to see the source code)

Yeah that's right, you can totally do that and a whole lot more with Markdown! In fact you can just write straight up HTML saved in .md extension format and it will run because the program rendering Markdown into HTML won't really have to do very much work! amirite? ;]

Changing the whole website backend for what is already present and easily implemented in Markdown rendering engines, why that would be like

like buying a forklift to carry a six-pack of beer.

[actionless]

or embed HTML into Markdown.

mb we should actually think into that direction, like just specifying filename, to avoid escaping any html syntax and stuff like that

UPD: actually it seems ikiwiki itself allows using both html and markdown as sources - https://ikiwiki.info/forum/transition_from_handwritten_html_to_ikiwiki/

your rendering platform will 99% handle this just fine

a bit bold claim considering all the set of tricks used to render it :)

[Aire-One]

Hello, this is your friendly reminder, that this thread is about sharing your tips-and-trick for your Awesome WM development environment.

Suggestion and discussion to change the current website (awesomewm.org) should be submitted to its GitHub repo at https://github.com/awesomeWM/awesome-www. Please remember that whatever cool and auto-magic framework out there, we don't plan to change its current stack.

Thanks everyone for your work to improve awesome!

[actionless]

I think the part with the guide itself actually also belongs to awesome-www, so i moved it all here

[actionless]

i recommends re-opening a new ticket for the remaining items (and if possible split to smaller tasks, and create accordingly in awesomeWM repo if it's smth to improve in the docs, or here if smth still left regarding improving website itself)