Description of Racket Distribution for download and package repo pages?

[spdegabrielle]

I think I’ve gone mad but I thought we had a summary of what was in the Racket distribution somewhere on https://racket-lang.org ?

@capfredf has kindly created a package for flathub, but it makes me think the lack of a summary on the download page is confusing for beginners? (especially those who have expectations from installing other popular languages)

Descriptions of what is included in the Racket Distribution are quite varied:

• https://flathub.org/apps/details/org.racket_lang.DrRacket

• https://snapcraft.io/racket

• more can be found via https://repology.org/project/racket/versions

Since I started composing I realised the following is on the racket wiki:

The Racket Distribution includes the Racket language(s), command line tools, and DrRacket IDE (but Racket is supported by a variety of IDE's and text editors )

It’s probably too short, but should something similar go on https://download.racket-lang.org/ ? (And everywhere the Racket Distribution is available ?)

Best regards & happy new year

Stephen

[sschwarzer]

Not an answer, but related:

What's official racket and what's not?

To someone new to Racket - looking at docs.racket-lang.org - this is basically a "soup" of things that seems to be an unordered brain dump of everything Racket related. I may have missed the memo buried on that website (can you blame me?) but if you do not know the history of all these projects (including Racket itself) - what qualifies a project to end up on that site? Are there indicators of how mature a particular project is? For example, is typed racket production quality? What about Rebell…

[capfredf]

It’s probably too short, but should something similar go on https://download.racket-lang.org/ ? (And everywhere the Racket Distribution is available ?)

Yes, I feel we could add the URLs for snap and flatpak in https://download.racket-lang.org/

[spdegabrielle]

@capfredf

Yes, I feel we could add the URLs for snap and flatpak in https://download.racket-lang.org/

+1

Are you up for making a PR?

[spdegabrielle]

This is what I’ve started telling people;

Racket is a modern lisp and a descendent of scheme. The Racket distribution includes an incremental native-code compiler*, the Racket language, Typed Racket & several other languages, IDE, documentation and a variety of other tools. The distribution is suitable for new learners, application development, or language design and implementation.

(* RacketScript - the Racket language implementation that compiles to Javascript - is also available separately)

But I’d phrase it differently for the downloads page

The Racket distribution includes an incremental native-code compiler, and implementations of the Racket language, Typed Racket & several other languages, IDE, documentation and many other tools.

The distribution is suitable for new learners, application development, or language design and implementation.

If you are new to Racket please see Getting Started in the documentation.

RacketScript - the Racket language implementation that compiles to Javascript - is available from https://github.com/racketscript/racketscript

I’d believe this could be the suggested text description when the Racket distribution is distributed via other package repositories including flathub, snap, homebrew, launchpad, etc.

Many of these have extensible programming language in the Scheme family, which does not accurately summarise the contents of the racket distribution.

Where there is a limitation on the space available, it should be cut from the bottom. e.g parts 1+2+3, 1+2, or just part 1, though all four -in order - is preferred.

I’ll do a PR to update https://download.racket-lang.org/

Best regards

Stephen

[capfredf]

I can do it later over the weekend.

Also, those download badges look nice. maybe we should use them on the racket download page?

[benknoble]

If I remember, I'll submit a PR to homebrew.

[benknoble]

Any suggestions for the minimal Racket formula?

Here's the PR for full Racket.

[spdegabrielle]

Minimal Racket: https://formulae.brew.sh/formula/minimal-racket

Should it have a different description

The Minimal Racket distribution includes the incremental native-code compiler, runtime and package management tool and is intended for resource-constrained server deployments.

Developers should use the full Racket Distribution.

the idea is that minimal is more like the JRE than the JDK.

S.

[soegaard]

For context:

Minimal-racket is very slow before installing compiler-lib

This is what I was expecting (just another lesson in the dangers of writing enormous paths by hand. This is also right. I definitely agree that making this work is important to giving a good first impression! I used Homebrew's minimal Racket myself for several Racket release cycles when I was relatively new to Racket. Adding an explicit raco setup step will definitely avoid the immediate problem, but I think it may be doing so by producing a duplicate set of .zo files. I'll try to descri…

[spdegabrielle]

Yes, it isn't the first time a beginner has had a bad experience because they tried to use the RRE instead of the RDK.

[spdegabrielle]

Took a look at https://github.com/racket/racket-lang-org/blob/master/download/download-pages.rkt and I have decided doing a PR safely is beyond my capacity at the moment.

Does anyone else wants to have a go at adding the following text`?

The Racket distribution includes an incremental native-code compiler, and implementations of the Racket language, Typed Racket & several other languages, IDE, documentation and many other tools.

The distribution is suitable for new learners, application development, or language design and implementation.

If you are new to Racket please see Getting Started in the documentation.

RacketScript - the Racket language implementation that compiles to Javascript - is available from GitHub - racketscript/racketscript: Racket to JavaScript Compiler

[alexh]

@spdegabrielle

The Minimal Racket distribution [...] is intended for resource-constrained server deployments.

For applications that run on a resource-constrained server, developers should install the full Racket distribution, and use raco exe and raco dist to create an application executable -- this will ensure the smallest possible size for the application and its module dependencies.

The problem with Minimal Racket is that, once you install a few packages required by your application, you'll end up with a "Maximal Racket" as soon as one of the packages depends on scribble or the test framework. Sure, some packages are split into "lib/test/doc" sub-packages, but not all of them, and you'll be putting the size of the final Racket installation at the mercy of some third-party package. raco exe + raco dist don't suffer from the same problem, as they will package only the required modules form a full Racket installation.

Even using Minimal Racket in the CI step for Github Actions for a Racket package, is a waste of time: a package that has documentation and tests (even if they are in separate "lib/doc/test" sub-packages), will end up installing the full Racket distribution, except it will take longer, since main distribution packages have to be installed separately one-by-one.

The only valid use-case I know for Minimal Racket is to setup build environments for working on one of the packages in the main Racket distribution, put it differently, Minimal Racket is a tool for the maintainers and developers of Racket itself.

Alex.

[sschwarzer]

@spdegabrielle

The Racket distribution includes an incremental native-code compiler, and implementations of the Racket language, Typed Racket & several other languages, IDE, documentation and many other tools.

What's meant here by "implementations of the Racket language"? Is this referring to BC vs. CS? If yes, it doesn't seem to me that it's important to refer to BC in the summary. My understanding was/is that the BC is legacy code now, so it should be omitted from the summary.

Besides that, the wording might be confusing, since if a user downloads the "distribution", they only get one language implementation, not both.

What is included in many tools (unless you count the raco commands individually)?

[spdegabrielle]

@alexh

Minimal Racket is a tool for the maintainers and developers of Racket itself.

Is it possible to ask homebrew and others to remove minimal racket?

[spdegabrielle]

I don’t mean bc, I mean it includes implementations of several languages including

• The Racket language
• Typed Racket
• Datalog

How about this

The Racket distribution includes an incremental native-code compiler, and implementations of several languages including Racket, Typed Racket & Datalog, Integrated development environment, all documentation and tools for application and language design, implementation, documentation and distribution.

Still need work. Keep the feed back coming

[sschwarzer]

Next iteration ...

The Racket distribution includes an incremental native-code compiler, several languages like Racket, Typed Racket and Datalog, as well as the DrRacket IDE. There are also documentation and tools for designing, implementing, documenting and distributing Racket applications and custom languages.

Reasons for the changes:

• I think "implementations of" is redundant.
• I used "as well as" to avoid/reduce ambiguous parsing ("languages like [Racket, Typed Racket, Datalog, integrated development environment]" vs."languages like Racket, Typed Racket, Datalog], integrated development environment". This change isn't strictly necessary because you'd arrive at the intended meaning after reading the sentence only three times.
• Mention "DrRacket" explicitly, so potential downloaders can do a web search on the IDE before actually downloading the distribution.
• In my opinion "IDE" is as understandable as "integrated development environment" and "IDE" makes the sentence easier to scan.
• I split the previous single sentence because I found it very difficult to read and understand. I don't insist on the specific wording "There are ..." though.
• In the last sentence I tried to get a bit away from the "nominal style" and using more verbs. Also now the "Racket applications and custom languages" are easier to tell apart from the actions on them.
• This is an iteration on your last text suggestion. I'm not against deriving/merging previous versions of the text.

[alexh]

@spdegabrielle

@alexh

Minimal Racket is a tool for the maintainers and developers of Racket itself.

Is it possible to ask homebrew and others to remove minimal racket?

Perhaps I should clarify that I didn't advocate removal of Minimal Racket from anywhere in my previous post.

Minimal Racket from homebrew is still useful: someone who wants to contribute to a package from the main distribution can install Minimal Racket from any source that they want, then setup the development environment for the package they want to contribute to, next they can test the package before submitting the PR.

To make the discussion more concrete, here is how one would setup an environment to work on the plot package (based on commands from the plot CI steps: https://github.com/racket/plot/blob/master/.github/workflows/ci.yml):

• Install Minimal Racket from your favorite source
• Clone the plot repository
• Setup a local catalog for plot, which takes precedence over then main catalog:

racket -l- pkg/dirs-catalog --link catalog .
echo "file://`pwd`/catalog" > catalogs.txt
raco pkg config catalogs >> catalogs.txt
raco pkg config --set catalogs `cat catalogs.txt`
raco pkg config catalogs

• Install the plot package -- this will install plot from the local checkout, and all other packages from the main catalog:

raco pkg install --batch --auto plot

With this setup, changes can be made to the plot package, tested and submitted as a PR. Of course, this works for any package, not just plot.

Alex.

[spdegabrielle]

Thanks @capfredf

@capfredf

Also, those download badges look nice. maybe we should use them on the racket download page?

A PR to https://github.com/racket/racket-lang-org/blob/master/www/download.rkt is beyond me at the moment, but we could put the badges on Installing Racket · racket/racket Wiki · GitHub as part of the effort to provide repository specific instructions: https://racket.discourse.group/t/installing-racket-from-package-repositories/1630?u=spdegabrielle. Let me know if I can help.

Best regards

S.

[spdegabrielle]

Thanks @alexh that is very helpful

Minimal Racket Distribution

Minimal Racket is a tool for the maintainers and developers of Racket to setup build environments for working on packages in the main Racket distribution. If you

• Install Minimal Racket from your favorite source
• Clone the repository for the main distribution package you want to work on
• Setup a local catalog for the cloned package, which takes precedence over then main catalog.
• Install the cloned package from the local checkout, and all other packages from the main catalog:

raco pkg install --batch --auto <main distribution package>

Changes can be made to the cloned package, tested and submitted as a PR. (see example steps for Plot package)
if you are not a maintainer of a package in the Racket distribution you should install/use the full Racket distribution.