Why does building something from Github have to be in a "secret" language and needlessly archaic with no real instructions?

[VERAULT]

I’m not sure it’s a terribly unreasonable expectation to assume that someone who has the wherewithal to flash a GAL should have a nodding familiarity with the standard tools associated with them. I guess I’d feel differently if this was something explicitly aimed at beginners, but the vibe I get from this repo is this is mainly here as an obligation because the guy who’s manufacturing these for sale based it on an open source project which, as is noted above, did have better documentation. (Presumably because he was actively trying to recruit collaboration help and *not* churn out things for sale.)

Anyway, with the repo with the GAL source being nothing but a .pld (which is the GAL source) and a .bat file this is where ”read the source”, the inevitable cost of free software, comes in. A quick peek at the batch file reveals you need WinCUPL to compile the .pld to a .Jed; how that gets burned into the GAL is beyond the scope because that of course will rely entirely on the software your particular programmer uses.

Here is what I dont understand.. Why cant they just post the JED files to load the gal? There are minuscule in size. Please really I dont understand. Explain why the files just cant be downloadable. What is the purpose of having to build them?

Remember shareware? If you liked it you could buy it? None of us were Building or compiling DOOM. We downloaded it, if we liked it we bought it. I just really dont get the reason for having to build files rather than just have them available for download. Are you supposed to have a feeling of accomplishment? it was made by someone else, they should feel that accomplishment. I just want to try it. I have better things to do then reinvent the wheel.


I understand I am coming across like "the old man" to the younger guys. But you dont see the situation clearly. I am trying to understand Github, and its not easy, there is a complete lack of proper documentation. And If I see it that way I can guarantee MANY MANY people see it that way.

Im not trying to poke it with a stick. I really want to understand how it all works. I LIKE to build projects. Its alot of fun in this hobby. And if this is the way things are heading I am trying to familiarize myself with it. How could that be a bad thing?

 

[Bruce Tomlin]

Why cant they just post the JED files to load the gal?

This. I can understand not uploading binaries for something where the output might change due to specifics of your configuration, but there is no such thing with GALs. There are literally only three types of GAL chips*, and one is chosen at the start of the project. It's important to have the source in there, yes, but there are just some types of build product that are stupid not to generate and check in.

Don't make me have to grovel around for another tool to build it, especially not something with "Win" in its name. It's also like not providing a PDF schematic with a project, and saying "just load it up in KiCAD and print to PDF, bro".

*yes, there are others, but they are obsolete, and the brand of the chip doesn't affect the .jed file

 

[Al Kossow]

"just load it up in KiCAD and print to PDF, bro".

oh, sorry I forgot to include all of my custom bodies. tough titties.
not including the pdf of the schematics is just being lazy or obstructive.

 

[Eudimorphodon]

Here is what I dont understand.. Why cant they just post the JED files to load the gal? There are minuscule in size. Please really I dont understand. Explain why the files just cant be downloadable. What is the purpose of having to build them?

Remember shareware?

So… here’s the deal: the comparison to “shareware” doesn’t really hold water here. There’s no “try before you buy” if you build a copy of a hardware project, the incentive to pay is gone once you’ve built a copy of it. So… I feel dirty making the following argument, but I guess it needs to be said:

I get that this lack of complete documentation feels like gatekeeping, and everyone not inside the clique doing it hates gatekeeping, but from a cynical point of view there’s some logic to intentionally making it a little hard for “just anyone” to run off a copy of a hardware project like this: if you limit the audience to technically skilled people it at least slightly improves the chances that the persons looking at it will actually want to participate/contribute technically to it.

Spending hours upon hours trying to make foolproof tutorial-level documentation has the potential to bite you two ways: as previously noted it might just end up making you liable for a lot of questions from newbies every time there’s a change in some toolchain component that is genuinely not a thing you want to deal with, and secondly, well, you might just be creating a howto guide for scalpers not capable of fully understanding or supporting the product to undercut what you’re charging. Which, sure, is going to happen anyway, but at least you’re making them work for it instead of you doing it all for them.

Some people are 100% happy doing “charity work” for others but this particular set of repositories is run by a outfit that would really like to get paid, so… yeah, take that for what it is.

 

[Eudimorphodon]

Don't make me have to grovel around for another tool to build it, especially not something with "Win" in its name.

WinCUPL is the pretty much the worst possible build chain dependency imaginable, given how incredibly flakey it is and hard it is to run on modern Windows versions (I ended up installing it in a 32 bit Debian VM and running it under WINE after failing to get it to do anything but immediately crash under Windows 10) so, yeah, I guess it does seem a little intentionally sadistic to not check in the .Jed, but per my previous post the cruelty may be the point.(*)

(* And it must be said, like it or not, WinCUPL is pretty much the only game in town for writing GAL code if you want niceties like address equations and a simulator. GALASM is my goto for simple jobs, and from what I saw in the .PLD file it’d probably be adequate for this project, but suffering through installing WinCUPL seems to be a standard rite of passage for being a GAL developer. And this repo clearly exists solely for the developers.)

 

[VERAULT]

fair enough and well explained. But I guess my retort would be this. Having complete control of hardware is fine.. Heck its the norm really. So why make it "open source" if the open part is more like pin holes rather than completely free and open. Just make it closed and sell it..

 

[Al Kossow]

I've seen people claim the repository is their documentation. If you have a question, just look at the code

 

[Eudimorphodon]

I've seen people claim the repository is their documentation. If you have a question, just look at the code

And if you’ve commented your code properly it’s not a terrible answer.

I mean, I get it, documentation sucks, even when people try to do it, but it’s not as if any technical writers are getting paid a salary to write manuals for every random Github project, let alone Heathkit-quality ones. Expectations should probably be set accordingly.

 

[Eudimorphodon]

So why make it "open source" if the open part is more like pin holes rather than completely free and open.

The guy who came up with the idea on a breadboard did his best and moved on. You’re looking at a fork maintained by a commercially-slanted entity who, to their credit, is honoring the original open source license and publishing their downstream changes. They’ve done what they were obliged to do, like I said, I’m not sure where the incentive lies for them to make it easier for them to not get paid.

… I mean, I get why you feel like it’s not “free”, because to use what’s there you’ll probably have to invest more hours understanding how to fit it all together than just buying the board is worth, but it is entirely “open” from what I can tell.

 

[Chuck(G)]

I mean, I get it, documentation sucks, even when people try to do it, but it’s not as if any technical writers are getting paid a salary to write manuals for every random Github project, let alone Heathkit-quality ones. Expectations should probably be set accordingly.

Writing good documentation is arduous. In some cases, it's more effort than writing the code. Few people appreciate this.

 

[Bruce Tomlin]

WinCUPL is pretty much the only game in town for writing GAL code

In a project where I have to burn GALs, I will include the .jed file. But in a fit of insanity* long ago, I wrote my own equivalent of galasm (with my own syntax, of course!). Even though it's just a vanilla command-line C program, it would be rude not to provide the .jed file. The equations file is mostly there just to document the .jed file anyhow.

*you have to be insane to comprehend it all (I got better)

 

[tradde]

So true about documentation. It's often left to the very end and the person wishes to move on to something else so may provide some. Sometimes that's worse than none.

 

[Eudimorphodon]

But in a fit of insanity* long ago, I wrote my own equivalent of galasm (with my own syntax, of course!).

Considering the strides that have been made in projects to reverse engineer PALs I sometimes think it’d be an interesting project to borrow some of that work and put together a working simulation extension to GALASM (maybe in addition to tacking on a macro language with some level of parity with what CUPL can do) since simulation is pretty much the only thing that keeps WinCUPL relevant for GALs. But, alas, I ain’t got time for that myself, and considering the size of the audience I certainly can’t ask anyone else to do it.

 

[dabone]

I make and sell wifi modems, and everything is on my github, and the documentation has taken me as long as actually designing some of the boards.

And it's not that long of documentation, it's just not my strong point to write it.
If I wasn't selling the boards, I don't think I would have invested the time to fully document them.

 

[Chuck(G)]

So true about documentation. It's often left to the very end and the person wishes to move on to something else so may provide some. Sometimes that's worse than none.

Writing good inline documentation for code is equally arduous. It really needs to be "Say what you're going to do; say what you're doing; then say what you've done" type of stuff. All the time including documentation for any variables, compile-time constants, etc.

I learned my professional coding skills working for a mainframe manufacturer on program modules that often spanned years and many tens of people. Strict coding standards needed to be observed, with code review sessions and explanations to the people in systems integration. And then there was writing the Internal Maintenance Specification.

This was all done back in the day of keypunching and writing on paper. But it burned some habits into my brain. I can read code that I wrote more than 40 years ago--I may not remember writing it or even hardware details of the platform--but my learned style didn't get in the way of understanding it.https://forum.vcfed.org/index.php?posts/1326347/edit

Of course, in this day of script kiddies and whatnot, things have gotten pretty awful in the name of maximizing production. After all, the code will be forgotten in 10 years, so why bother creating the Great Coding Novel?

I could see the tendency when looking at some kernel mode drivers for Windows NT 3.1 and comparing them with the same code for Windows Vista. The former was clear and accurate; the later was sloppy and often done without updating the commentary.

 

[epooch]

In a project where I have to burn GALs, I will include the .jed file. [...] it would be rude not to provide the .jed file. The equations file is mostly there just to document the .jed file anyhow.

Here is what I dont understand.. Why cant they just post the JED files to load the gal? There are minuscule in size. Please really I dont understand. Explain why the files just cant be downloadable. What is the purpose of having to build them?

I just checked a repository I have and sure enough, I did not include the JED file, only the equations. Adding it feels like including a binary with the source code. It is completely useless for me to edit or understand. The JED file is just an intermediate file for my purposes. I guess I don't have enough experience with GAL programming to understand why that would be more useful to anybody than the equations. The only other time I have used a project with a GAL, I had to ask the author if he could send me the equations so I could actually make it do what I wanted.

 

[vwestlife]

Cut them some slack. They're probably using vi. That's why so few of them are masochistic enough to use it to write complete and detailed documentation!

 

[VERAULT]

Yeah I am not really hearing a valid excuse for not including the complete files though. Why would you only make a piece of hardware that caters to programmers. Are these modern software types really under the impression that everyone (including hardware people) know as much about code as they do?

The only point made that seems to make any plausible sense it @Eudimorphodon stating its made in a way to only allow contributors (same skill-set people) to further add to the project.

 

[tradde]

I happen to like using VI. Just cause you don't doesn't mean it's bad. I also enjoyed using TECO on the pdp-10.

 

[Svenska]

Including binaries (or any form of generated files) within a source repository risks forgetting to update them when the code changes and risks building a dependency to them which shouldn't exist. Both problems will cause trouble later, when things do not work as expected.