add some explanation of aaa-auto.R generation in CONTRIBUTING.md

[maelle]

Obviously asking for a friend :sweat_smile:

[krlmlr]

Maybe a reference to https://github.com/igraph/rigraph/blob/main/src/README.md, and document there?

I agree the current docs are sparse.

[maelle]

yes, pointing to external docs would be good.

Maybe with some sort of FAQ/guide: how to find whether the function you want to modify was generated automatically (it lives in aaa-auto.R) in particular.

[maelle]

some inspiration for the contributing guide https://arrow.apache.org/docs/r/articles/index.html#developer-guides

[szhorvat]

That's a great contributor's guide that would of course be nice to have. The bottleneck is the time required to write it. Another problem is that the infrastructure is in flux at the moment.

I'd suggest drafting a guide in the GitHub wiki. If you figure out something that wasn't properly documented, feel free to write it down there. Once we have something solid, it can be migrated to a public location like CONTRIBUTORS.md

It's easier to add to a wiki than a public location. The writing doesn't have to be perfect, you can first write and later ask if it's accurate, and generally make quicker progress.

[maelle]

current status of my using the generation #850

[krlmlr]

I use:

docker run --rm -ti --platform linux/amd64 -v $(pwd):/root/workspace ghcr.io/cynkra/rig-ubuntu-igraph:main make -f Makefile-cigraph

for full reproducibility. The only noisy things are lex and yacc, we could add version checks here too.

[maelle]

what should pwd be?

[maelle]

I am not sure I understand how one would actually run the command.

[szhorvat]

The only noisy things are lex and yacc

Let's call these flex and bison. We do use extensions provided by GNU Flex and GNU Bison.

Not sure what version you're using now, but I strongly recommend the latest Bison, namely 3.8.2. Bison 3.8 generates better end-user error messages (i.e. messages that igraph users will see) than earlier versions.

As for Flex, it hasn't had a release in ages. Any platform we might ever use should have Flex 2.6.4.

[krlmlr]

Run

docker run --rm -ti --platform linux/amd64 -v $(pwd):/root/workspace ghcr.io/cynkra/rig-ubuntu-igraph:main make -f Makefile-cigraph

from a local clone of this repository. With this, $(pwd) expands to the right location.

Just checked, we have the right versions in our Docker image:

docker run --rm -ti --platform linux/amd64 -v $(pwd):/root/workspace ghcr.io/cynkra/rig-ubuntu-igraph:main bison --version
# bison (GNU Bison) 3.8.2
# Written by Robert Corbett and Richard Stallman.
#
# Copyright (C) 2021 Free Software Foundation, Inc.
# This is free software; see the source for copying conditions.  There is NO
# warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
docker run --rm -ti --platform linux/amd64 -v $(pwd):/root/workspace ghcr.io/cynkra/rig-ubuntu-igraph:main flex --version
# flex 2.6.4

[krlmlr]

Add -B to rerun everything in the Makefile.

[maelle]

Notes for myself at the moment.

I edited functions-R.yaml. Running the code with -B didn't change R/aaa-auto.R. I need to add an argument for the path.

[maelle]

https://github.com/igraph/rigraph/issues/1176#issuecomment-1916988433

[maelle]

it worked, I feel so empowered :smiling_imp:

[maelle]

Now trying to work out how to expose a function with no argument.

[maelle]

In 6356a50 (#1229) I don't know how to have no argument in res <- .Call(R_igraph_version, ). I tried editing functions-R.yaml too.

[maelle]

idea: add an .Rbuildignored R file with an R function that'd wrap the commands for regenerating the code.