Move FAQ & Known Issues to manual
These sections are valid parts of the manual and just clutter up the current README
This commit is contained in:
parent
2e636ef43e
commit
67d0c03a54
46
README.md
46
README.md
|
@ -154,52 +154,6 @@ Roadmap
|
||||||
See [the roadmap](ROADMAP.md) for the current plan. Help on any of
|
See [the roadmap](ROADMAP.md) for the current plan. Help on any of
|
||||||
these points is welcome!
|
these points is welcome!
|
||||||
|
|
||||||
FAQ
|
|
||||||
---
|
|
||||||
|
|
||||||
### Why do many Jbuilder projects contain a Makefile?
|
|
||||||
|
|
||||||
Many Jbuilder project contain a toplevel `Makefile`. It is often only
|
|
||||||
there for convenience, for the following reasons:
|
|
||||||
|
|
||||||
1. there are many different build systems out there, all with a
|
|
||||||
different CLI. If you have been hacking for a long time, the one
|
|
||||||
true invocation you know is `make && make install`, possibly
|
|
||||||
preceded by `./configure`
|
|
||||||
|
|
||||||
2. you often have a few common operations that are not part of the
|
|
||||||
build and `make <blah>` is a good way to provide them
|
|
||||||
|
|
||||||
3. `make` is shorter to type than `jbuilder build @install`
|
|
||||||
|
|
||||||
### How to add a configure step to a jbuilder project?
|
|
||||||
|
|
||||||
[example/sample-projects/with-configure-step](example/sample-projects/with-configure-step) shows
|
|
||||||
one way to do it which preserves composability; i.e. it doesn't require manually
|
|
||||||
running `./configure` script when working on multiple projects at the same time.
|
|
||||||
|
|
||||||
### Can I use topkg with jbuilder?
|
|
||||||
|
|
||||||
Yes, have a look at the [topkg-jbuilder][topkg-jbuilder] project for
|
|
||||||
more details.
|
|
||||||
|
|
||||||
### Where can I find some examples of projects using Jbuilder?
|
|
||||||
|
|
||||||
The [dune-universe](https://github.com/dune-universe/dune-universe)
|
|
||||||
repository contains a snapshot of the latest versions of all opam packages
|
|
||||||
depending on jbuilder. It is therefore a useful reference to search through
|
|
||||||
to find different approaches to constructing build rules.
|
|
||||||
|
|
||||||
Known issues
|
|
||||||
------------
|
|
||||||
|
|
||||||
### mli only modules
|
|
||||||
|
|
||||||
These are supported, however using them might cause make it impossible
|
|
||||||
for non-jbuilder users to use your library. We tried to use them for
|
|
||||||
some internal module generated by Jbuilder and it broke the build of
|
|
||||||
projects not using Jbuilder:
|
|
||||||
|
|
||||||
https://github.com/ocaml/dune/issues/567
|
https://github.com/ocaml/dune/issues/567
|
||||||
|
|
||||||
So, while they are supported, you should be careful where you use
|
So, while they are supported, you should be careful where you use
|
||||||
|
|
|
@ -0,0 +1,40 @@
|
||||||
|
***
|
||||||
|
FAQ
|
||||||
|
***
|
||||||
|
|
||||||
|
Why do many Jbuilder projects contain a Makefile?
|
||||||
|
=================================================
|
||||||
|
|
||||||
|
Many Jbuilder project contain a toplevel `Makefile`. It is often only there for
|
||||||
|
convenience, for the following reasons:
|
||||||
|
|
||||||
|
1. there are many different build systems out there, all with a different CLI.
|
||||||
|
If you have been hacking for a long time, the one true invocation you know is
|
||||||
|
`make && make install`, possibly preceded by `./configure`
|
||||||
|
|
||||||
|
2. you often have a few common operations that are not part of the build and
|
||||||
|
`make <blah>` is a good way to provide them
|
||||||
|
|
||||||
|
3. `make` is shorter to type than `jbuilder build @install`
|
||||||
|
|
||||||
|
How to add a configure step to a jbuilder project?
|
||||||
|
==================================================
|
||||||
|
|
||||||
|
[example/sample-projects/with-configure-step](example/sample-projects/with-configure-step)
|
||||||
|
shows one way to do it which preserves composability; i.e. it doesn't require
|
||||||
|
manually running `./configure` script when working on multiple projects at the
|
||||||
|
same time.
|
||||||
|
|
||||||
|
Can I use topkg with jbuilder?
|
||||||
|
==============================
|
||||||
|
|
||||||
|
Yes, have a look at the [topkg-jbuilder][topkg-jbuilder] project for
|
||||||
|
more details.
|
||||||
|
|
||||||
|
here can I find some examples of projects using Jbuilder?
|
||||||
|
=========================================================
|
||||||
|
|
||||||
|
The [dune-universe](https://github.com/dune-universe/dune-universe) repository
|
||||||
|
contains a snapshot of the latest versions of all opam packages depending on
|
||||||
|
jbuilder. It is therefore a useful reference to search through to find different
|
||||||
|
approaches to constructing build rules.
|
|
@ -19,3 +19,5 @@ Welcome to jbuilder's documentation!
|
||||||
api-doc
|
api-doc
|
||||||
usage
|
usage
|
||||||
advanced-topics
|
advanced-topics
|
||||||
|
faq
|
||||||
|
known-issues
|
||||||
|
|
|
@ -0,0 +1,17 @@
|
||||||
|
************
|
||||||
|
Known Issues
|
||||||
|
************
|
||||||
|
|
||||||
|
mli only modules
|
||||||
|
================
|
||||||
|
|
||||||
|
These are supported, however using them might cause make it impossible for
|
||||||
|
non-jbuilder users to use your library. We tried to use them for some internal
|
||||||
|
module generated by Jbuilder and it broke the build of projects not using
|
||||||
|
Jbuilder:
|
||||||
|
|
||||||
|
https://github.com/ocaml/dune/issues/567
|
||||||
|
|
||||||
|
So, while they are supported, you should be careful where you use them. Using a
|
||||||
|
`.ml` only module is still preferable.
|
||||||
|
|
Loading…
Reference in New Issue