Integrate build instructions into the GHDL documentation #280
Comments
|
These are the files I found, which I think could be moved to the doc:
However,
Additional notes:
|
|
On 13/02/17 23:58, 1138-4EB wrote:
[...]
However,
* I think that it is still interesting to keep a copy of 'COPYING' and
a minimum version of 'BUILD.txt' in the root. Maybe just extending
the section in the |./README| can be enough, instead of 'BUILD.txt'.
At the same time, 'COPYING' can be written in markdown and copied to
|doc| as 'License' on readthedocs deploy.
Please, do not modify COPYING as that's legal stuff. It is OK to get an
official COPYING.md (if that does exist) from the FSF, but otherwise
keep it as it.
If you need a short license section in the doc, just use the same text
as in the source files (and give an url to the full license).
I'd prefer to keep building instructions in README short so that
newcomers aren't afraid by it. But I am ok with moving BUILD.txt to the
doc.
The doc targets the end user. It is ok to have a chapter on
building/installing ghdl (as well as a chapter on the internals), but if
that gets too long, I think we'd better to have two doc.
* It'd be very useful to add a README/INSTALL and COPYING to each
release. Some parts of the |doc| can be used to generate these on
travis-ci deploy.
Yes.
* I'd add a specific 'NEWS' section (maybe renamed to 'Release log'),
but keep the file in the root (renamed to |*.md|) so that it is
copied on deploy.
Yes.
* |dist/gcc/README|, |dist/gcc/INSTALL| and |dist/mcode/README| would
go directly to the doc.
Most of them are outdated, so it's ok to merge them in the doc.
* No idea where to put |dist/gcc/ANNOUNCE|. But I think that it should
be kept somewhere.
Very old file, not used anymore. To be removed ?
Tristan.
|
Just a pair of weeks ago: https://gist.github.com/jnrbsn/708961#gistcomment-1984787 Readthedocs allows to show multiple versions (see [example], bottom left). I tried to activate branches
Two doc? Or one in master and another one in a different branch? I think it is easier to try to keep it in a single doc with separated chapters. It it gets too long, I think that a
Proposed to save it because it seems to be your very first announce of GHDL, isn't it? Just for nostalgic reasons then. By the way, there are some additional branches/tags shown in the readthedocs settings:
Are they used for something? |
|
On 14/02/17 08:34, 1138-4EB wrote:
Please, do not modify COPYING as that's legal stuff. It is OK to get
an official COPYING.md (if that does exist) from the FSF, but
otherwise keep it as it.
Just a pair of weeks ago:
https://gist.github.com/jnrbsn/708961#gistcomment-1984787
https://www.gnu.org/licenses/gpl-3.0.md
That would be ok (but ghdl is gpl v2+)
------------------------------------------------------------------------
Readthedocs allows to show multiple versions (see [example], bottom
left). I tried to activate branches |ghdl-0.31|, |ghdl-0.32|,
|ghdl-0.33|, but it looks like there was still no a readthedocs-prepared
|doc|. I think, it would be interesting to activate at least two
versions from now on: the lates stable realease (0.33 now) and the
pre-release/dev-release/nightly-release (0.34-dev now).
Yes, that's a good idea.
The doc targets the end user. It is ok to have a chapter on
building/installing ghdl (as well as a chapter on the internals),
but if that gets too long, I think we'd better to have two doc.
Two doc? Or one in master and another one in a different branch? I think
it is easier to try to keep it in a single doc with separated chapters.
It it gets too long, I think that a |dev-doc| branch can be more useful
than having two doc dirs.
Ok, make sense.
Very old file, not used anymore. To be removed ?
Proposed to save it because it seems to be your very first announce of
GHDL, isn't it? Just for nostalgic reasons then.
Well, it is not lost. It is in git. I am not sure this is the very
first announce. And it is now confusing.
For nostalgic people, git log -p is a better answer.
Tristan.
|
https://www.gnu.org/licenses/old-licenses/gpl-2.0.html |
|
On 18/02/17 05:39, 1138-4EB wrote:
That would be ok (but ghdl is gpl v2+)
https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
https://www.gnu.org/licenses/old-licenses/gpl-2.0.md
Yes!
I wasn't able to find them from the FSF page. Thanks.
|
|
Since the content of BUILD.txt is moved to the docs, what shall we do with this line? |
|
@tgingold |
|
Yes, we should select the right ortho-lang.c according to the gcc version. |
|
@tgingolg, should the contributor list be included in Copyrights or in Contributing? |
|
On 20/02/17 19:02, 1138-4EB wrote:
Should the contributor list be included in Copyrights
<http://ghdl-devfork.readthedocs.io/en/new-documentation-structure/intro/Copyrights.html>
or in Contributing
<http://ghdl-devfork.readthedocs.io/en/new-documentation-structure/intro/Contributing.html>?
I would say in Copyrights.
|
|
@tgingold, what do you think about adding a Contributers License Agreement to the project? The following example is taken from PoC:
|
|
We would need a CLA for GPLv2. Both existing CLA services are not really good, but CLAHub seems to develop new features whereas the SAP service (CLAassistant) hasn't seen any updates ... Are there other services that integrate into GitHub? Python uses a special service from Adobe :( |
I think that it can be covered with http://contributoragreements.org/chooser/ However, I wanted to discuss about requiring it, since some/any potential contributors might not bother to contribute if they are required to sign.
I'm really new to this. Just saw your example and thought it is worth talking about it. I read this and then I found the following statement here:
Note the part I put in bold. If we add this requirement, it'd be great to have that option, so that it is just a checkbox when creating a new PR. There are still a few flaws:
|
|
Both mentioned services offer a CSV file for download. CLA assistant is GIST based what I dislike, but supports CLA versioning CLA hub has a nicer integration. Contributing is then limited to PRs or we know we have a signed CLA for this users private repository. I must not contain content from other users. I can give you access to a test repo or you create your own playground :) |
I'm quite busy now, leaving the doc tidy. We'll wait to see what @tgingold thinks, and I will ask you for access then ;) |
|
On 21/02/17 02:47, 1138-4EB wrote:
I can give you access to a test repo or you create your own
playground :)
I'm quite busy now, leaving the doc tidy. We'll wait to see what
@tgingold <https://github.com/tgingold> thinks, and I will ask you for
access then ;)
I have mixed feelings for CLA.
First, I think we must not require CLA for small contributions (like a
typo fix). Does PoC require CLA in that case ?
Second, I wonder if CLA prevents some users from contributing. Any
experience ?
Apart from that, I'm ok and I think this is a good idea if for any
reason we want to change the copyright.
|
|
We got one fix before the CLA was active. Currently, CLAs are active for all PRs, but a maintainer can merge even if the CLA plugin says unsigned. It's like a Travis did not build message, You can ignore it. But the user still sees the demand to sign the CLA while he submits the PR. As far as I know all bigger open source projects go for CLAs. I have to sign one for Python (through a weird Acrobat online signing service). In case of Apache, everything is included in the original License. The CLA is more or less an explicit notice that one rule of the License will now be applied to your code snippet :) |
|
As an intermediate solution, is there any way to show a note and a checkbox when a user is to send a PR? Contributing to a project explicitly licensed under GPLv2 implies giving the code under known conditions. Taking the idea of the Apache CLA, we could just provide a note claiming attention on the fact that they are contributing under GPLv2 (and/or CC-BY-SA-40). The difference between this and the CLA is that the username and email in the commit would be enough to identify the user. The CLA requires more personal data, doesn't it? If such a note is not possible, we could just make it clear in the 'Contributing' page, apart from 'Copyrights'. |
|
On 22/02/17 05:33, Patrick Lehmann wrote:
We got one fix before the CLA was active. Currently, CLAs are active for
all PRs, but a maintainer can merge even if the CLA plugin says
unsigned. It's like a Travis did not build message, You can ignore it.
But the user still sees the demand to sign the CLA while he submits the PR.
That's Ok.
As far as I know all bigger open source projects go for CLAs. I have to
sign one for Python (through a weird Acrobat online signing service).
Did you sign on your own or did your employer sign ?
For individual, CLA is somewhat easy. For employees, that could be much
more difficult.
In case of Apache, everything is included in the original License. The
CLA is more or less an explicit notice that one rule of the License will
now be applied to your code snippet :)
We could adopt the same strategy.
|
|
On 22/02/17 05:47, 1138-4EB wrote:
As an intermediate solution, is there any way to show a note and a
checkbox when a user is to send a PR? Contributing to a project
explicitly licensed under GPLv2 implies giving the code under known
conditions. Taking the idea of the Apache CLA, we could just provide a
note claiming attention on the fact that they are contributing under
GPLv2 (and/or CC-BY-SA-40).
Note that this is GPLv2+, that is version 2.0 or later.
The difference between this and the CLA is that the username and email
in the commit would be enough to identify the user. The CLA requires
more personal data, doesn't it?
That's my understanding and a concern. Did you ever sign a CLA ?
If such a note is not possible, we could just make it clear in the
'Contributing' page, apart from 'Copyrights'.
Yes, that's a possibility.
There is one big only advantage of a CLA: it allows to change the license.
Currently the license if GPLv2+ (and with exceptions in the runtime).
|
I'm a student, every code is mine :). But on the other hand, In Germany, your employer doesn't need to sign for your private code. It only applies to code created during work time. So it's not so restrictive like in the US where you have to ask your employer for every code snippet you want to supply.
At that point, it's important to use well known CLAs or licenses in general, so they have to do only one check per license name/version.
Are you thinking of changing the license? Personally I don't like GPL but that's why I write libraries and no end user tools. I'm OK with GPL if I contribute snippets. |
No, I did not. I just read the quoted part from PoC, the references there, and these: |
|
On 22/02/17 05:58, Patrick Lehmann wrote:
Did you sign on your own or did your employer sign ?
I'm a student, every code is mine :). But on the other hand, In Germany,
your employer doesn't need to sign for your private code. It only
applies to code created during work time. So it's not so restrictive
like in the US where you have to ask your employer for every code
snippet you want to supply.
Ah, that's the easy case.
For individual, CLA is somewhat easy. For employees, that could be
much more difficult.
At that point, it's important to use well known CLAs or licenses in
general, so they have to do only one check per license name/version.
Yes, for sure.
We could adopt the same strategy.
The GPL doesn't work that way as far as I know.
I mean: just remind contributor that the work is covered by GPLv2+ or
CC-by-SA.
Did you ever sign a CLA ?
I can send you a copy of my CLA for Python. (private email)
I see.
it allows to change the license.
Does GPL allow to change the license?
I am not a lawyer, but here is my understanding.
This is not really a matter of license. You are the author of your
work, so you have the copyright. By contributing it (asking for a pull
request), you agree to follow the GPLv2+ license (as GHDL is licensed
under GPLv2+). But I (as GHDL maintainer) cannot say: "thank you, I
will also release it under a commercial license" because I don't have
the copyright of your contribution. So we are locked in GPLv2+.
Now there is a clause in the GPLv2+ that allows any later version than 2.
Are you thinking of changing the license?
No, I'm ok with GPLv2+.
The question is more about grt, the runtime.
Personally I don't like GPL
Why ?
but that's why I write libraries and no end user tools. I'm OK with GPL
if I contribute snippets.
Ok.
Tristan.
|
|
@tgingold, still, you could remove the contributions made by others and, if needed, reimplement those yourself. Most of the contributions are auxiliary to the GHDL core, isn't it? Not proposing it, just pushing the case to the limit. |
|
On 22/02/17 06:22, 1138-4EB wrote:
@tgingold <https://github.com/tgingold>, still, you could remove the
contributions made by others and, if needed, reimplement those yourself.
Most of the contributions are auxiliary to the GHDL core, isn't it? Not
proposing it, just pushing the case to the limit.
Yes, that's what I would have to do if I wanted to create a non-GPLv2+
version of ghdl, ie only use parts I have written. But no, I don't want
to do that.
Once you will have rewritten the doc, it would be much difficult for the
doc!
|
Please, don't you dare compare a 15 years of works with less than a week effort! |
|
@tgingold, I am with the QuickStartGuide now:
Does that depend on you/GHDL or is GtkWave which needs to be adapted? Is it somewhere in your todo's? Not trying to push it up, I just want to have a reference to write a sentence about it. It seems that interactive or pseudo-interactive simulation for Verilog is supported. Then, I think it is worth mentioning, so that people who have previously used icarus (because of icestorm) are aware of the differences. Making it explicit might help contributions.
|
|
On 24/02/17 16:37, 1138-4EB wrote:
@tgingol, I am with the QuickStartGuide now:
*
Exporting to GtkWave is mentioned. Currently the following formats
are supported by GtkWave: VCD, FST, LXT, LXT2, VZT, and GHW.
However, supports 'only' three of them (VCD, FST and GHW). Shall I
move |--vcd=<FILENAME>|, |--vcdgz=<FILENAME>|, |--fst=<FILENAME>|and
|--wave=<FILENAME>| from |GHDL Usage / Simulation and runtime /
Simulation options| a new subsection named |GHDl Usage / Simulation
and runtime / Export waves|? The point is to add a brief explanation
on why those three formats where chosen only. I'm not making it
imply it is insufficient, but to explain why other additional
formats add no functionality.
Yes, creating a new subsection may be useful as these options form a group.
*
On top of that, in the manual
<http://gtkwave.sourceforge.net/gtkwave.pdf> of GtkWave, this is said:
Source code annotation is currently not available for VHDL, however
all of GTKWave's other debug features are readily accessible. VHDL
support is planned for a future release.
Does that depend on you/GHDL or is GtkWave which needs to be adapted? Is
it somewhere in your todo's? Not trying to push it up, I just want to
have a reference to write a sentence about it. It seems that interactive
or pseudo-interactive simulation for Verilog is supported. Then, I think
it is worth mentioning, so that people who have previously used icarus
(because of icestorm) are aware of the differences. Making it explicit
might help contributions.
That's something that could be added in the future, but I have no plan
for it.
Tristan.
|
|
@tgingold, thanks. Just edited. Can you check the last two questions? |
|
Sorry, I missed them from the email. The json format is not documented, except it should be self-documented. Maybe worth adding a small example ? The XML format (for --file-to-xml) is not documented and it may change as it shows internal stuff. --no-run can be useful for gcc/llvm/mcode. It simply stops simulation just before the first cycle. But it can be used to display the hierarchy (with --disp-tree). |
I'll put a todo and recheck when I arrive there.
I get it. With GCC/LLVM, it does something besides disp-tree? Will any check be done with was not done during elaboration? |
|
On 24/02/17 19:05, 1138-4EB wrote:
The json format is not documented, except it should be
self-documented. Maybe worth adding a small example ?
I'll put a todo and recheck when I arrive there.
--no-run can be useful for gcc/llvm/mcode. It simply stops
simulation just before the first cycle. But it can be used to
display the hierarchy (with --disp-tree).
I get it. With GCC/LLVM, it does something besides disp-tree? Will any
check be done with was not done during elaboration?
it actually performs elaboration, while '-e' mostly gather object files
and link them together.
So --no-run will catch any bound error in port maps.
|
|
Then, as a final clarification, it is not exactly the same to run the binary executable generated after Since I've always used the mcode version, I thought that the binary generated with GCC/LLVM was a replace for GHDL. That is, that I could distribute that binary alone, without GHDL itself. |
|
On 24/02/17 19:19, 1138-4EB wrote:
Then, as a final clarification, it is not exactly the same to run the
binary executable generated after |-e| directly, than to actually use
|-r|?
No, it's the same. With gcc/llvm, 'ghdl -r xxx' simply executes ./xxx
Is it only true for the first example of the Quick Start Guide
where a single VHDL Hello world program is compiled?
Since I've always used the mcode version, I thought that the binary
generated with GCC/LLVM was a replace for GHDL. That is, that I could
distribute that binary alone, without GHDL itself.
Yes, you can distribute the binary alone without ghdl (with gcc/llvm).
I fear I am not yet clear enough...
|
|
On 24/02/17 19:52, 1138-4EB wrote:
You are. It is just that I know very little about the internal process
(steps) of a compiler. I'm used to writing fully static and really small
programs. Therefore, it is difficult for me to get how much of GHDL's
functionality is put into that binary. Is it just that the core of GHDL
is the runtime library (grt), so both GHDL and any generated binary just
use the same resources?
Yes, they use the same code. I wouldn't say that grt is the core of
GHDL, but it's the simulator kernel.
BTW, you can have a look at the modifications:
http://ghdl-devfork.readthedocs.io/en/alt-new/using/QuickStartGuide.html
These questions are just to make sure that nothing in there is incorrect.
Typo: the option for utf-8 is --mb-comments or -C (not --mb).
I like the tip boxes.
But I would order the boxes differently. The quick start guide should
be easy to read: so use a simple workflow (-a, -e, then -r). Many users
don't really know whether they are using gcc, llvm or mcode backend.
Then, at the end of the section you can add the tip boxes explaining
that -e is optional with mcode and the program can be started directly
with llvm/gcc).
Thank you for all this work,
Tristan.
|
|
I thought we had partially merged this to master, and the remaining parts where docker and longer tutorials. My bad. I rebased, updated, cleaned up and rechecked it. I think it is ready to merge now: #482. |
This is a collective issue to gather notes and workitems for the integration of the build documentation into the official documentation on ReadTheDocs.
I think we need a new table of contents structure like this:
The text was updated successfully, but these errors were encountered: