On 10/05/2019 16:19, Jeremy Huntwork wrote: > On Wed, May 8, 2019 at 8:37 AM Pierre Labastie <[email protected]> > wrote: >> >> Hi, >> >> After some discussion in an pull request at github [1], it's been decided to >> move the discussion to this list. >> >> Let's first (attempt to) summarize [1]: Jeremy attempted to write a Python >> wrapper to the current jhalfs script, which was working well, but differently >> from the usual jhalfs. So it was first decided to change the code in order to >> have the same behavior as before. That turned out to be difficult without >> adding some ad hoc code, which eventually would have become needlessly >> complicated. It was then decided to start from scratch. I then asked for some >> planning ahead. Jeremy then closed the pull request, and we decided to move >> the planning to this list. >> >> I'd like to propose here a structure for the internal data of the jhalfs >> program. This is open to discussion, of course. In the following, I propose >> objects and attributes to those objects. I do not want to tell how those >> attributes are assigned to, nor how they are used. Just have a data structure >> universal enough so that different types of books can be fit in. Note that >> the >> following is informal: the aim is to fix where the information should be >> stored, not how (dictionary, list, string, number, ...). >> >> [... description of the structure ...]] > > This generally sounds like a good approach. I hesitate to call out a > specific design outside of the code, mostly because I believe the code > should document well the design and it should also allow for some > flexibility as we learn best how to organize and test. But I do think > organizing by objects is a good way to look at it and I understand you > are trying to avoid unbounded sprawl that becomes unmaintainable. > > So I think in that spirit it would be good to highlight just a few more > things. > > 1. Have some kind of goal or mission statement for the code. Is the > purpose to automate just xLFS style books, or is it a more generic > bootstrapping tool? What would constitute out-of-scope? Try to keep it > high level, but specific enough so that when new ideas or suggestions > arise, we can firmly decide if it matches defined scope for the tool.
Let me tell how I see it. I know it is a very personal view. So please, don't see it as immutable or engraved in stone. It seems to me that there are a number of sources about building/bootstrapping a 'Do It Yourself' linux system. Those I know are: - LFS - CLFS (lack maintenance, but still usable) - HLFS (defunct) - DIY linux (defunct) - BLFS/CBLFS - merelinux (more recent, using rst as a markup language) There are certainly others, sometimes directly executable, such as Kegel crosstools (http://kegel.com/crosstool/), but without explanations for the rationales behind. If we restrict to those sources containing explanations, they are written with some markup language, and can be rendered with standard tools. Then a user can copy the instructions to build its own system. What I see as lacking (except jhalfs) is a way to extract instructions from those sources, to automatically generate scripts that can be run to build the system. This is very important in testing the instructions. For example, let's suppose the maintainer of one of those sources tries successfully a new build method, and wants to put it in. So this person has working scripts, and edits the source to reflect what is in the scripts. Now comes the time to test that what is in the book is what is in the scripts. That's where we enter the scene with our tool. So our tool is roughly a function with: - input: a source (call it a 'book') - output: a set of scripts with a way to run them in order. The scripts can be in a "spec" format for a package manager, and the "way to run" can be a package manager... Whether this function is a webapp (suggested by Bryan), a local app (as it is now), and the choice of language used for writing it (presently XSLT+bash, coming Python) may be adapted, changed, etc. Now let me come to what I see as outside or inside the tool: - writing books is outside our scope. But we may suggest improvements to authors... - test new bootstrap methods is outside our scope (we need somebody to write a "book" for it), but once a book is written, we can adapt our tool to the book and the requirements of the build method: for example, whether we need to introduce a new kind of user with specific privileges, or of container (chroot, boot a VM, use virtual envs, lxc containers, etc). - introduce new packages (for "beyond" type of books) is outside our scope, except if they are needed for the proper use of the tool (for example adding a package manager, a library for reading a particular book format, etc) > 2. Let testability drive the shape of the code itself. Sometimes you > have a structure well in mind for how the code should look and it > makes a lot of sense, very organized and logical. But something > specific about it makes it hard to test. Since testing drives quality, > relaxing the design a little as you learn how best to test the code > can make a huge difference. Agreed. Since we are writing a (big) function, we'll need to write inputs (that is, book snippets) and require they produce known outputs, and test that. Of course, we may also have tests for parts of the tool, and I agree plainly with the principles you set above. Testing whether a book produces a viable system is outside our scope (but our tool should be used by others for that). > 3. Try to include in the code the structure required for good > documentation, both when reading the code directly and possibly for > auto-generating html docs, like with sphinx: > http://www.sphinx-doc.org/en/stable/ Agreed. AFAIK, Python as a good infrastructure for that. It's harder with the present XSLT/bash language! What is usually not in the docs is "instructions for use": those are the hardest to write, but we should if we want to have users :) Pierre -- http://lists.linuxfromscratch.org/listinfo/alfs-discuss FAQ: http://www.linuxfromscratch.org/faq/ Unsubscribe: See the above information page
