Re: [Amforth] Gory Details: How to properly create a release?

[Erich <ew....@na...>]

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