search

fable-compiler / Fable

F# to JavaScript, TypeScript, Python, Rust and Dart Compiler
http://fable.io/
MIT License
2.92k stars 300 forks source link

Some more getting started docs? #462

Closed simra closed 7 years ago

simra commented 8 years ago

Description

Fable could use some additional docs/helper tools for newbies.

Repro steps

If I git clone and build.cmd, how do I invoke the fable I just built? All the docs point to using npm to install fable which as far as I can tell pulls the public packages. Where are the install instructions from a local repo? When I launch most browser samples using "start index.html" I get a blank page (in Edge and Chrome on Windows) or non-functional sample. I suspect this is because I need to host the sample on a real web server, rather than just launching index.html directly. To that end, some pointers to standing up a simple local web server, or even providing a server stub, for example using Suave, in the repo would be helpful. It would be awesome if users could clone the repo, build it, and launch an fsx that hosts all the samples locally.

Expected behavior

Getting started with Fable should be easy! :-)

I'm happy to help contribute here but some pointers for where to start would be helpful.

alfonsogarciacaro commented 8 years ago

You're right, we should put README files in every sample folder. For now, as you can run most of samples in the same way, I'll listen the steps here:

  1. It's not actually necessary to build fable first (you can just download from npm and install it globally with npm install -g fable-compiler, but if you want to run the development version, after building it, from the repo root dir type node build/fable plus the compiler arguments (adjust the relative path if you're in another dir).
  2. There's a node static server, but you must first compile it. Following the instructions above, you can run node build/fable samples/node/server (Fable will read the options from fableconfig.json in that folder). You need to do this only once.
  3. Now let's say you want to compile the pacman sample, run node build/fable samples/browser/pacman (add -w if you want to start Fable in watch mode).
  4. To start a local server, you must go to the directory you want to serve the files from (in this case, samples/browser/pacman) and from there call the JS-compiled node static server: node ../../node/server/out and in the browser open localhost:8080 (you can also pass a different port when calling the node script).

Repeating steps 3 and 4 should work for most browser samples.

I hope this helps! Please tell me if you've more questions :+1:

tpetricek commented 8 years ago

I was actually thinking about this recently too - the samples are great for the web site and to showcase what Fable can do, but they're not as easy to start with - and I think this is partly because they're in a large repo.

I think it would be nice if we had maybe 3 typical "fable-compiler/getting-started" projects or templates that people can just clone, run and then start modifying...

simra commented 8 years ago

Thanks, this was super-helpful. I drafted an INSTALL.md file for you to have a look here: https://github.com/simra/Fable/blob/master/INSTALL.md I'm happy to take any feedback and create the PR. I could also put a top-level index.html or README.md in the samples folder but wonder if you'd prefer to have it auto-generated at build time (eg to enumerate all the samples). @tpetricek, for a getting started project I wonder if the best thing would be to fork the Elm demo that's here: http://fable.io/samples/virtualdom/index.html

alfonsogarciacaro commented 8 years ago

@simra Thanks a lot for that! I think the README is good as is :+1: Could you please send a PR to put it in the samples directory?

About a common index.html, I've followed a somewhat similar approach in fable-graphics. There's no common index.html there, but a slightly modified version of the static server which can received the directory to server the files from as an argument and fire up the browser, so all samples can be run with the same command. Here is a bit more difficult because the samples are more heterogenous and some links may fail if the sample dir is not the server root. And there's also the issue of keeping the index.html in sync with new samples. But if you want to give it a try of course you're very welcome to send a PR with an index.html to run several samples at once. However, as mentioned the samples are mainly to support the website and to experiment new features, so they may not be the best fit for getting started tutorials. We may have to do that in a separate repo as proposed.

@tpetricek I totally agree with you. I also think that, as Fable is a lightweight compiler, currently the samples assume both knowledge of F# and JS tooling, which is not always the case. We're planning to create a more opinionated fable-powerpack (in a separate repo) to make it easier for newcomers to get started. For that, I need to make some changes to Fable so it's easier to package and distribute Fable libraries. When this is done, we can create the getting-started project and, if time allows, a Fable introduction for non-F# devs :+1:

@tpetricek

simra commented 8 years ago

Hi, here is the PR for the readme: #468. I'll have a look at the samples and see if I can provide an overview index.html and some simple launch instructions.