Improve README to be more structural and more readable (#2814)
This commit is contained in:
Owen Ou authored and GitHub committed
1 parent
ff4bf68b29
commit
53a62cf2b0
1 file changed
+39
-55
@@ -1,76 +1,60 @@
|
||||
jq
|
||||
==
|
||||
# jq
|
||||
|
||||
jq is a lightweight and flexible command-line JSON processor.
|
||||
`jq` is a lightweight and flexible command-line JSON processor akin to`sed`,`awk`,`grep`, and friends for JSON data. It's written in portable C and has zero runtime dependencies, allowing you to easily slice, filter, map, and transform structured data.
|
||||
|
||||
If you want to learn to use jq, read the documentation at
|
||||
[https://jqlang.github.io/jq](https://jqlang.github.io/jq). This
|
||||
documentation is generated from the docs/ folder of this repository.
|
||||
You can also try it online at [jqplay.org](https://jqplay.org).
|
||||
## Documentation
|
||||
|
||||
If you want to hack on jq, feel free, but be warned that its internals
|
||||
are not well-documented at the moment. Bring a hard hat and a
|
||||
shovel. Also, read the wiki: https://github.com/jqlang/jq/wiki, where
|
||||
you will find cookbooks, discussion of advanced topics, internals,
|
||||
release engineering, and more.
|
||||
- **Official Documentation**: [jqlang.github.io/jq](https://jqlang.github.io/jq)
|
||||
- **Try jq Online**: [jqplay.org](https://jqplay.org)
|
||||
|
||||
Source tarball and built executable releases can be found on the
|
||||
homepage and on the github release page, https://github.com/jqlang/jq/releases.
|
||||
Docker image is available at https://github.com/jqlang/jq/pkgs/container/jq.
|
||||
## Installation
|
||||
|
||||
If you're building directly from the latest git, you'll need libtool, make, automake,
|
||||
and autoconf installed.
|
||||
To get regexp support you'll also need to install Oniguruma or clone it as a
|
||||
git submodule as per the instructions below. To build, run:
|
||||
### Prebuilt Binaries
|
||||
|
||||
git submodule update --init # if building from git to get oniguruma
|
||||
autoreconf -i # if building from git
|
||||
./configure --with-oniguruma=builtin
|
||||
make -j8
|
||||
make check
|
||||
Download the latest releases from the [GitHub release page](https://github.com/jqlang/jq/releases).
|
||||
|
||||
Developers must `--enable-maintainer-mode` when making changes to the
|
||||
jq parser and lexer which also requires bison and flex to be installed.
|
||||
### Docker Image
|
||||
|
||||
To build a statically linked version of jq, run:
|
||||
Pull the [jq image](https://github.com/jqlang/jq/pkgs/container/jq) to start quickly with Docker.
|
||||
|
||||
make LDFLAGS=-all-static
|
||||
### Building from source
|
||||
|
||||
After make finishes, you'll be able to use `./jq`. You can also
|
||||
install it using:
|
||||
#### Dependencies
|
||||
|
||||
sudo make install
|
||||
- libtool
|
||||
- make
|
||||
- automake
|
||||
- autoconf
|
||||
|
||||
If you're not using the latest git version but instead building a
|
||||
released tarball (available on the website), then you won't need to
|
||||
run `autoreconf` (and shouldn't), and you won't need flex or bison.
|
||||
#### Instructions
|
||||
|
||||
To cross-compile for OS X and Windows, see docs/Rakefile's build task
|
||||
and scripts/crosscompile. You'll need a cross-compilation environment,
|
||||
such as Mingw for cross-compiling for Windows.
|
||||
```console
|
||||
git submodule update --init # if building from git to get oniguruma
|
||||
autoreconf -i # if building from git
|
||||
./configure --with-oniguruma=builtin
|
||||
make -j8
|
||||
make check
|
||||
sudo make install
|
||||
```
|
||||
|
||||
Cross-compilation requires a clean workspace, then:
|
||||
Build a statically linked version:
|
||||
|
||||
# git clean ...
|
||||
autoreconf -i
|
||||
./configure
|
||||
make distclean
|
||||
scripts/crosscompile <name-of-build> <configure-options>
|
||||
```console
|
||||
make LDFLAGS=-all-static
|
||||
```
|
||||
|
||||
Use the `--host=` and `--target=` ./configure options to select a
|
||||
cross-compilation environment. See also
|
||||
["Cross compilation"](https://github.com/jqlang/jq/wiki/Cross-compilation) on
|
||||
the wiki.
|
||||
If you're not using the latest git version but instead building a released tarball (available on the release page), skip the `autoreconf` step, and flex or bison won't be needed.
|
||||
|
||||
To compile jq to WebAssembly, install the [Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html), then:
|
||||
##### Cross-Compilation
|
||||
|
||||
git submodule update --init # if building from git to get oniguruma
|
||||
autoreconf -i # if building from git
|
||||
emconfigure ./configure --with-oniguruma=builtin
|
||||
emmake make EXEEXT=.js CFLAGS="-O2" LDFLAGS="-s EXPORTED_RUNTIME_METHODS=['callMain']"
|
||||
For details on cross-compliation, check out the [GitHub Actions file](.github/workflows/ci.yml) and the [cross-compliation wiki page](https://github.com/jqlang/jq/wiki/Cross-compilation).
|
||||
|
||||
## Community & Support
|
||||
|
||||
# Community
|
||||
- Questions & Help: [Stack Overflow (jq tag)](https://stackoverflow.com/questions/tagged/jq)
|
||||
- Chat & Community: [Join us on Discord](https://discord.gg/yg6yjNmgAC)
|
||||
- Wiki & Advanced Topics: [Explore the Wiki](https://github.com/jqlang/jq/wiki)
|
||||
|
||||
* Send questions to https://stackoverflow.com/questions/tagged/jq.
|
||||
* Join our [Discord server](https://discord.gg/yg6yjNmgAC).
|
||||
## License
|
||||
|
||||
`jq` is released under the [MIT License](COPYING).
|
||||
Reference in new issue
Block a user