Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve README #2814

Merged
merged 3 commits into from
Aug 3, 2023
Merged

Improve README #2814

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
93a5717
Improve README
owenthereal Aug 1, 2023
26e0e93
Remove unecessary heading
owenthereal Aug 2, 2023
09d6796
Clarify release tarball build
owenthereal Aug 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 42 additions & 53 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,76 +1,65 @@
jq
==

jq is a lightweight and flexible command-line JSON processor.
## Introduction
owenthereal marked this conversation as resolved.
Show resolved Hide resolved

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).
**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 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.
## Getting Started
owenthereal marked this conversation as resolved.
Show resolved Hide resolved

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.
### Documentation

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:
- **Official Documentation**: [jqlang.github.io/jq](https://jqlang.github.io/jq)
- **Try jq Online**: [jqplay.org](https://jqplay.org)

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
## Installation

Developers must `--enable-maintainer-mode` when making changes to the
jq parser and lexer which also requires bison and flex to be installed.
### Prebuilt Binaries

To build a statically linked version of jq, run:
Download the latest releases from the [GitHub release page](https://github.com/jqlang/jq/releases).

make LDFLAGS=-all-static
### Docker Image

After make finishes, you'll be able to use `./jq`. You can also
install it using:
Pull the [jq image](https://github.com/jqlang/jq/pkgs/container/jq) to start quickly with Docker.

sudo make install
### Building from source

If you're not using the latest git version but instead building a
owenthereal marked this conversation as resolved.
Show resolved Hide resolved
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.
#### Dependencies

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.
- libtool
- make
- automake
- autoconf

Cross-compilation requires a clean workspace, then:
#### Instructions

# git clean ...
autoreconf -i
./configure
make distclean
scripts/crosscompile <name-of-build> <configure-options>
```console
git submodule update --init # if building from git to get oniguruma
autoreconf -i # if building from git
./configure --with-oniguruma=builtin
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I always feel --with-oniguruma=builtin in instruction is verbose because it detects automatically but do we still need this to prevent the fallback to pre-installed libonig?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Indeed, the --with-oniguruma=builtin is in the default ./configure flags: . Perhaps let's make the help more clear builtin is the default.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess this is going to be more reliable for users, so it's probably best to leave it. Users with a slight clue will think about this and maybe exclude this option?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I understand.

make -j8
make check
sudo make install
```

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.
Build a statically linked version:

To compile jq to WebAssembly, install the [Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html), then:
```console
make LDFLAGS=-all-static
```

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']"
To build from a released tarball (available on the release page), skip the `autoreconf` step, and flex or bison won't be needed.

##### Cross-Compilation

# Community
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).
nicowilliams marked this conversation as resolved.
Show resolved Hide resolved

* Send questions to https://stackoverflow.com/questions/tagged/jq.
* Join our [Discord server](https://discord.gg/yg6yjNmgAC).
## Community & Support

- 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)

## License

`jq` is released under the [MIT License](COPYING).