More details on Point 4 (see below).
Cheers,
Erich
Erich Wälde writes:
Dear AmForthers,
I asked:
- How do I actually create a new release? Copying the files is
one thing, but where do I need to change the version? There
is more than one place, I'm afraid. I also happen to know
that after 6.9 there cannot be 6.10 due to a limitation
created very early. Matthias told me that, otherwise I would
be clueless.
see https://sourceforge.net/p/amforth/mailman/message/37048278/
How to create an official release?
I spent some time to do some code archeology. I still do not know,
how to properly make a release. This is, what I currently
see/expect:
1. check all version numbers in trunk
- doc/Makefile being one place. This seems to be used in all
generated documentation, which is nice.
- common/words/env-forthversion.asm is another place with different
syntax!
Judging by commit r2271, these are all places indeed. Yay!
2. update doc/source/index.rst and optionally history.rst in
trunk and commit
3. "svn copy" trunk to releases/$VERSION; commit message collects
the accumulated one line change descriptions
This is the most visible change in the source tree
e.g. see commit r2244 (rel 6.5)
4. create all .hex files for target boards in appl/
arduino,atmega2561,eval-pollin,hifive1,launchpad-arm,launchpad430,
template
I had forgotten that these exsisted. They are in the release archive
only, not in the source tree. Now I understand, why people
sometimes ask about them.
This step is detailed in a few .xml files. Matthias used ant to
build them. I have not built these before, but this looks doable,
provided I get all relevant toolchains up and running.
Digging through the ./appl/ subdirectory I think I understand the
following:
- There are currently 8 target directories.
- all of them have either build.xml or Makefile files
- of the AVR8 targets all can be build with the exception of
"arduino/leonardo" --- this runs into the "8k is too small"
limitation. There used to be an avr-butterfly target (up to
6.4), which suffers from the same limitation, iirc.
AVR needs the wine/avrasm2.exe toolchain.
- the remaining targets need different toolchains, which I have not
installed at this moment.
- hifive1 riscv64-linux-gnu-as
In the download section Matthias has provided a toolchain, see:
https://sourceforge.net/projects/amforth/files/Risc-V-Tools/
However, this toolchain is very hip today, so it is available
at den Debian repositories as well: gcc-riscv64-linux-gnu/stable
I actually have such a board collecting dust in the corner :-/
- launchpad-arm arm-none-eabi-as
This toolchain is available at the debian repositories as well:
gcc-arm-none-eabi/stable
- launchpad430 naken_asm
This tool is available, maintained and probably quite mature:
http://www.mikekohn.net/micro/naken_asm.php
In 2015 I have made experiments with this toolchain, so this
part is probably doable.
- inux-arm arm-linux-gnueabi-as
This toolchain is available at the debian repositories as well:
gcc-arm-linux-gnueabi/stable
I do not have any msp430 or arm boards any more. I have given
them away.
So all in all, the toolchains are available. Matthias has
probably built a bunch of docker containers to run them :-)
A little while later:
Installing the missing toolchains on Debian turns out to be
fairly simple (thank you, Debianistas!):
# apt install binutils-riscv64-linux-gnu \
binutils-arm-linux-gnueabi \
binutils-arm-none-eabi
I had a copy of naken_asm (from 201(5) in some corner and with
that executable on the PATH, I could build launchpad430
So with the exception of arduino/leonardo.* I managed to build
everything that shows up in the release archive.
ew@ceres:~/Forth/amforth/trunk/appl 119 > ls -l */*.hex */amforth
-rw-r----- 1 ew ew 239 2020-08-30 11:28 arduino/duemilanove.eep.hex
-rw-r----- 1 ew ew 26843 2020-08-30 11:28 arduino/duemilanove.hex
-rw-r----- 1 ew ew 239 2020-08-30 11:28 arduino/mega128.eep.hex
-rw-r----- 1 ew ew 27959 2020-08-30 11:28 arduino/mega128.hex
-rw-r----- 1 ew ew 239 2020-08-30 11:28 arduino/uno.eep.hex
-rw-r----- 1 ew ew 27157 2020-08-30 11:28 arduino/uno.hex
-rw-r----- 1 ew ew 239 2020-08-30 11:31 atmega2561/atmega256.eep.hex
-rw-r----- 1 ew ew 27481 2020-08-30 11:31 atmega2561/atmega256.hex
-rw-r----- 1 ew ew 239 2020-08-30 11:27 eval-pollin/p1284-16.eep.hex
-rw-r----- 1 ew ew 28096 2020-08-30 11:27 eval-pollin/p1284-16.hex
-rw-r----- 1 ew ew 239 2020-08-30 11:27 eval-pollin/p16-8.eep.hex
-rw-r----- 1 ew ew 27518 2020-08-30 11:27 eval-pollin/p16-8.hex
-rw-r----- 1 ew ew 239 2020-08-30 11:27 eval-pollin/p32-8.eep.hex
-rw-r----- 1 ew ew 27682 2020-08-30 11:27 eval-pollin/p32-8.hex
-rw-r----- 1 ew ew 239 2020-08-30 11:27 eval-pollin/p328-16.eep.hex
-rw-r----- 1 ew ew 27771 2020-08-30 11:27 eval-pollin/p328-16.hex
-rw-r----- 1 ew ew 239 2020-08-30 11:27 eval-pollin/p644-16.eep.hex
-rw-r----- 1 ew ew 27796 2020-08-30 11:27 eval-pollin/p644-16.hex
-rw-r----- 1 ew ew 47833 2020-08-30 13:17 hifive1/hifive1.hex
-rw-r----- 1 ew ew 44449 2020-08-30 13:23 launchpad-arm/lp-stellaris.hex
-rw-r----- 1 ew ew 23068 2020-08-30 13:12 launchpad430/lp-2553.hex
-rw-r----- 1 ew ew 23132 2020-08-30 13:12 launchpad430/lp-5529.hex
-rw-r----- 1 ew ew 22568 2020-08-30 13:12 launchpad430/lp-5969.hex
-rwxr-x--- 1 ew ew 68528 2020-08-30 13:20 linux-arm/amforth*
-rw-r----- 1 ew ew 239 2020-08-30 11:34 template/template.eep.hex
-rw-r----- 1 ew ew 27475 2020-08-30 11:34 template/template.hex
This pretty much solves point 4
So the whole thing more "shell script like"
cd /path/to/../amforth/trunk
( cd avr8; ln -s /path/to/AvrAssembler2 ./Atmel )
cd appl
# these are avr targets
# arduino fails on leonardo (8k too small problem)
for DIR in arduino atmega2561 eval-pollin template
do
( cd $DIR; ant compile )
done
sudo apt install binutils-riscv64-linux-gnu \
binutils-arm-linux-gnueabi \
binutils-arm-none-eabi
for DIR in hifive1 launchpad-arm linux-arm
do
( cd $DIR; make )
done
# remove the "git-info" dependency from launchpad430/build.xml
( cd launchpad430; make lp-2553.hex lp-5529.hex lp-5969.hex )
5. create the documentation
- htdocs, the web page
- books, did you know that all the content of the webpage shows up
in amforth.pdf (made with pdflatex) and AmForth.epub (made with
sphinx-build)? Amazing! These books are part of the download .zip
archive.
This step is a "cd doc; make all" --- provided sphinx pdflatex
and all the good stuff is installed.
6. create a new temporary tree to collect everything, that goes into
the release archive:
- sources
- some of the scripts, tools, meta-files
- the generated documentation from releases/$VERSION, without the
document sources, but including the "books"
I have not found anything that looks like doing this.
7. create the .zip and .tar.gz archives (the easy part), and upload
them to their correct location in the sourceforge.net file tree
(the not so obvious part).
I found out that these release archives were built by Matthias.
The files for 6.8 are about 7 MB in size.
Whereas if you download "the latest sources", sourceforge will
generate a snapshot of "trunk". This is a plain copy, without all
the niceties included in the archives mentioned here. This archive
is currently 35 MB in size.
8. sync the generated documentation with the online website
I have done this a few times now, but I'm still asking myself, if I
see all relevant pieces or not.
9. Increment the version numbers in trunk and commit
So nine easy steps to code nirvana? Hmmm.
If anyone has some insight or detail I'm missing, I would be
happy to hear about it. I propose to rework this into a .rst
document and add it to the source tree, once missing bits have
emerged (points 4, 6, 7).
Cheers,
Erich
_______________________________________________
Amforth-devel mailing list for http://amforth.sf.net/
Amforth-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/amforth-devel
