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:
Rudi Grinberg
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
|
||||
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
|
||||
|
||||
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
|
||||
usage
|
||||
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