~ninjin/julia-nix

6ca7ead51defd3955371bd6868f6cd42c1c3adc7 — Pontus Stenetorp 3 years ago 3794f9a
nix: Alternative README for fork
2 files changed, 209 insertions(+), 172 deletions(-)

M README.md
A README.md.orig
M README.md => README.md +37 -172
@@ 1,172 1,37 @@
<a name="logo"/>
<div align="center">
<a href="https://julialang.org/" target="_blank">
<img src="doc/src/assets/logo.svg" alt="Julia Logo" width="210" height="142"></img>
</a>
</div>

Documentation:
[![Documentation][docs-img]][docs-url]

[docs-img]: https://img.shields.io/badge/docs-v1-blue.svg "Documentation (version 1)"
[docs-url]: https://docs.julialang.org

Continuous integration:
[![Continuous integration (master)][buildkite-master-img]][buildkite-master-url]
[![Continuous integration (master->scheduled)][buildkite-master-scheduled-img]][buildkite-master-scheduled-url]

<!--
To change the badge to point to a different pipeline, it is not sufficient to simply change the `?branch=` part.
You need to go to the Buildkite website and get the SVG URL for the correct pipeline.
-->
[buildkite-master-img]: https://badge.buildkite.com/f28e0d28b345f9fad5856ce6a8d64fffc7c70df8f4f2685cd8.svg?branch=master "Continuous integration (master)"
[buildkite-master-url]: https://buildkite.com/julialang/julia-master

<!--
To change the badge to point to a different pipeline, it is not sufficient to simply change the `?branch=` part.
You need to go to the Buildkite website and get the SVG URL for the correct pipeline.
-->
[buildkite-master-scheduled-img]: https://badge.buildkite.com/d5ae34dbbf6fefe615300c4f3118bf63cb4a5ae7fd962263c1.svg?branch=master "Continuous integration (master->scheduled)"
[buildkite-master-scheduled-url]: https://buildkite.com/julialang/julia-master-scheduled

Code coverage:
[![Code coverage (Coveralls)][coveralls-img]][coveralls-url]
[![Code coverage (Codecov)][codecov-img]][codecov-url]

[coveralls-img]: https://img.shields.io/coveralls/github/JuliaLang/julia/master.svg?label=coveralls "Code coverage (Coveralls)"
[coveralls-url]: https://coveralls.io/r/JuliaLang/julia?branch=master

[codecov-img]: https://img.shields.io/codecov/c/github/JuliaLang/julia/master.svg?label=codecov "Code coverage (Codecov)"
[codecov-url]: https://codecov.io/github/JuliaLang/julia?branch=master

## The Julia Language

Julia is a high-level, high-performance dynamic language for technical
computing.  The main homepage for Julia can be found at
[julialang.org](https://julialang.org/).  This is the GitHub
repository of Julia source code, including instructions for compiling
and installing Julia, below.

## Resources

- **Homepage:** <https://julialang.org>
- **Binaries:** <https://julialang.org/downloads/>
- **Source code:** <https://github.com/JuliaLang/julia>
- **Documentation:** <https://docs.julialang.org>
- **Packages:** <https://julialang.org/packages/>
- **Discussion forum:** <https://discourse.julialang.org>
- **Slack:** <https://julialang.slack.com> (get an invite from <https://julialang.org/slack/>)
- **YouTube:** <https://www.youtube.com/user/JuliaLanguage>
- **Code coverage:** <https://coveralls.io/r/JuliaLang/julia>

New developers may find the notes in
[CONTRIBUTING](https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md)
helpful to start contributing to the Julia codebase.

### External Resources

- [**StackOverflow**](https://stackoverflow.com/questions/tagged/julia-lang)
- [**Twitter**](https://twitter.com/JuliaLanguage)
- [**Learning resources**](https://julialang.org/learning/)

## Binary Installation

If you would rather not compile the latest Julia from source,
platform-specific tarballs with pre-compiled binaries are also
[available for download](https://julialang.org/downloads/). The
downloads page also provides details on the
[different tiers of support](https://julialang.org/downloads/#support-tiers)
for OS and platform combinations.

If everything works correctly, you will see a Julia banner and an
interactive prompt into which you can enter expressions for
evaluation.  You can read about [getting
started](https://docs.julialang.org/en/v1/manual/getting-started/) in the manual.

**Note**: Although some system package managers provide Julia, such
installations are neither maintained nor endorsed by the Julia
project. They may be outdated, broken and/or unmaintained. We
recommend you use the official Julia binaries instead.

## Building Julia

First, make sure you have all the [required
dependencies](https://github.com/JuliaLang/julia/blob/master/doc/build/build.md#required-build-tools-and-external-libraries) installed.
Then, acquire the source code by cloning the git repository:

    git clone https://github.com/JuliaLang/julia.git

By default you will be building the latest unstable version of
Julia. However, most users should use the most recent stable version
of Julia. You can get this version by changing to the Julia directory
and running:

    git checkout v1.6.2

Now run `make` to build the `julia` executable.

Building Julia requires 2GiB of disk space and approximately 4GiB of virtual memory.

**Note:** The build process will fail badly if any of the build directory's parent directories have spaces or other shell meta-characters such as `$` or `:` in their names (this is due to a limitation in GNU make).

Once it is built, you can run the `julia` executable after you enter your julia directory and run

    ./julia

Your first test of Julia determines whether your build is working
properly. From the UNIX/Windows command prompt inside the `julia`
source directory, type `make testall`. You should see output that
lists a series of running tests; if they complete without error, you
should be in good shape to start using Julia.

You can read about [getting
started](https://docs.julialang.org/en/v1/manual/getting-started/)
in the manual.

In case this default build path did not work, detailed build instructions
are included in the [build documentation](https://github.com/JuliaLang/julia/blob/master/doc/build).

### Uninstalling Julia

Julia does not install anything outside the directory it was cloned
into. Julia can be completely uninstalled by deleting this
directory. Julia packages are installed in `~/.julia` by default, and
can be uninstalled by deleting `~/.julia`.

## Source Code Organization

The Julia source code is organized as follows:

| Directory         | Contents                                                           |
| -                 | -                                                                  |
| `base/`           | source code for the Base module (part of Julia's standard library) |
| `stdlib/`         | source code for other standard library packages                    |
| `cli/`            | source for the command line interface/REPL                         |
| `contrib/`        | editor support for Julia source, miscellaneous scripts             |
| `deps/`           | external dependencies                                              |
| `doc/src/manual/` | source for the user manual                                         |
| `doc/build/`      | detailed notes for building Julia                                  |
| `src/`            | source for Julia language core                                     |
| `test/`           | test suites                                                        |
| `usr/`            | binaries and shared libraries loaded by Julia's standard libraries |

## Terminal, Editors and IDEs

The Julia REPL is quite powerful. See the section in the manual on
[the Julia REPL](https://docs.julialang.org/en/v1/stdlib/REPL/)
for more details.

On Windows we highly recommend running Julia in a modern terminal,
such as [Windows Terminal from the Microsoft Store](https://aka.ms/terminal).

Support for editing Julia is available for many
[widely used editors](https://github.com/JuliaEditorSupport):
[Emacs](https://github.com/JuliaEditorSupport/julia-emacs),
[Vim](https://github.com/JuliaEditorSupport/julia-vim),
[Sublime Text](https://github.com/JuliaEditorSupport/Julia-sublime), and many
others.

Supported IDEs include: [julia-vscode](https://github.com/JuliaEditorSupport/julia-vscode) (VS
Code plugin), [Juno](http://junolab.org/) (Atom plugin). [Jupyter](https://jupyter.org/)
notebooks are available through the [IJulia](https://github.com/JuliaLang/IJulia.jl) package, and
[Pluto](https://github.com/fonsp/Pluto.jl) notebooks through the Pluto.jl package.
**julia-nix** is a [Julia][julia] fork with patches to make building and
development work with [Nix and NixOS][nix]. Patches related to specific release
branches are kept in their respective branches with names mirroring the
[upstream Julia repository][upstream]; `master` tracks the ongoing development
upstream but with patches added to make hacking on Julia feasible from NixOS.

[julia]: https://julialang.org
[nix]: https://nixos.org
[upstream]: https://github.com/JuliaLang/julia

For example, this is how you build the latest `master`:

```sh
> git clone git@git.sr.ht:~ninjin/julia-nix
> cd julia-nix
> git pull --rebase git@github.com:JuliaLang/julia.git
> nix-shell --pure --run make
> ./julia --print VERSION
v"1.7.0-DEV.909"
```

From this point onward you can hack on Julia as usual, produce patches, and
submit them upstream. Alternatively, you can export and apply the patches from
this repository to your own Julia fork.

Beware that rebases and history edits are common as the goal of this repository
is not to track the development of the Nix-specific patches themselves, but
rather to keep the history minimally different relative to the upstream Julia
repository.

Lastly, if you want to talk about Nix/NixOS and Julia, feel free to join us in
the #nix channel over on the [official Julia Slack][slack].

[slack]: https://julialang.org/slack

A README.md.orig => README.md.orig +172 -0
@@ 0,0 1,172 @@
<a name="logo"/>
<div align="center">
<a href="https://julialang.org/" target="_blank">
<img src="doc/src/assets/logo.svg" alt="Julia Logo" width="210" height="142"></img>
</a>
</div>

Documentation:
[![Documentation][docs-img]][docs-url]

[docs-img]: https://img.shields.io/badge/docs-v1-blue.svg "Documentation (version 1)"
[docs-url]: https://docs.julialang.org

Continuous integration:
[![Continuous integration (master)][buildkite-master-img]][buildkite-master-url]
[![Continuous integration (master->scheduled)][buildkite-master-scheduled-img]][buildkite-master-scheduled-url]

<!--
To change the badge to point to a different pipeline, it is not sufficient to simply change the `?branch=` part.
You need to go to the Buildkite website and get the SVG URL for the correct pipeline.
-->
[buildkite-master-img]: https://badge.buildkite.com/f28e0d28b345f9fad5856ce6a8d64fffc7c70df8f4f2685cd8.svg?branch=master "Continuous integration (master)"
[buildkite-master-url]: https://buildkite.com/julialang/julia-master

<!--
To change the badge to point to a different pipeline, it is not sufficient to simply change the `?branch=` part.
You need to go to the Buildkite website and get the SVG URL for the correct pipeline.
-->
[buildkite-master-scheduled-img]: https://badge.buildkite.com/d5ae34dbbf6fefe615300c4f3118bf63cb4a5ae7fd962263c1.svg?branch=master "Continuous integration (master->scheduled)"
[buildkite-master-scheduled-url]: https://buildkite.com/julialang/julia-master-scheduled

Code coverage:
[![Code coverage (Coveralls)][coveralls-img]][coveralls-url]
[![Code coverage (Codecov)][codecov-img]][codecov-url]

[coveralls-img]: https://img.shields.io/coveralls/github/JuliaLang/julia/master.svg?label=coveralls "Code coverage (Coveralls)"
[coveralls-url]: https://coveralls.io/r/JuliaLang/julia?branch=master

[codecov-img]: https://img.shields.io/codecov/c/github/JuliaLang/julia/master.svg?label=codecov "Code coverage (Codecov)"
[codecov-url]: https://codecov.io/github/JuliaLang/julia?branch=master

## The Julia Language

Julia is a high-level, high-performance dynamic language for technical
computing.  The main homepage for Julia can be found at
[julialang.org](https://julialang.org/).  This is the GitHub
repository of Julia source code, including instructions for compiling
and installing Julia, below.

## Resources

- **Homepage:** <https://julialang.org>
- **Binaries:** <https://julialang.org/downloads/>
- **Source code:** <https://github.com/JuliaLang/julia>
- **Documentation:** <https://docs.julialang.org>
- **Packages:** <https://julialang.org/packages/>
- **Discussion forum:** <https://discourse.julialang.org>
- **Slack:** <https://julialang.slack.com> (get an invite from <https://julialang.org/slack/>)
- **YouTube:** <https://www.youtube.com/user/JuliaLanguage>
- **Code coverage:** <https://coveralls.io/r/JuliaLang/julia>

New developers may find the notes in
[CONTRIBUTING](https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md)
helpful to start contributing to the Julia codebase.

### External Resources

- [**StackOverflow**](https://stackoverflow.com/questions/tagged/julia-lang)
- [**Twitter**](https://twitter.com/JuliaLanguage)
- [**Learning resources**](https://julialang.org/learning/)

## Binary Installation

If you would rather not compile the latest Julia from source,
platform-specific tarballs with pre-compiled binaries are also
[available for download](https://julialang.org/downloads/). The
downloads page also provides details on the
[different tiers of support](https://julialang.org/downloads/#support-tiers)
for OS and platform combinations.

If everything works correctly, you will see a Julia banner and an
interactive prompt into which you can enter expressions for
evaluation.  You can read about [getting
started](https://docs.julialang.org/en/v1/manual/getting-started/) in the manual.

**Note**: Although some system package managers provide Julia, such
installations are neither maintained nor endorsed by the Julia
project. They may be outdated, broken and/or unmaintained. We
recommend you use the official Julia binaries instead.

## Building Julia

First, make sure you have all the [required
dependencies](https://github.com/JuliaLang/julia/blob/master/doc/build/build.md#required-build-tools-and-external-libraries) installed.
Then, acquire the source code by cloning the git repository:

    git clone https://github.com/JuliaLang/julia.git

By default you will be building the latest unstable version of
Julia. However, most users should use the most recent stable version
of Julia. You can get this version by changing to the Julia directory
and running:

    git checkout v1.6.2

Now run `make` to build the `julia` executable.

Building Julia requires 2GiB of disk space and approximately 4GiB of virtual memory.

**Note:** The build process will fail badly if any of the build directory's parent directories have spaces or other shell meta-characters such as `$` or `:` in their names (this is due to a limitation in GNU make).

Once it is built, you can run the `julia` executable after you enter your julia directory and run

    ./julia

Your first test of Julia determines whether your build is working
properly. From the UNIX/Windows command prompt inside the `julia`
source directory, type `make testall`. You should see output that
lists a series of running tests; if they complete without error, you
should be in good shape to start using Julia.

You can read about [getting
started](https://docs.julialang.org/en/v1/manual/getting-started/)
in the manual.

In case this default build path did not work, detailed build instructions
are included in the [build documentation](https://github.com/JuliaLang/julia/blob/master/doc/build).

### Uninstalling Julia

Julia does not install anything outside the directory it was cloned
into. Julia can be completely uninstalled by deleting this
directory. Julia packages are installed in `~/.julia` by default, and
can be uninstalled by deleting `~/.julia`.

## Source Code Organization

The Julia source code is organized as follows:

| Directory         | Contents                                                           |
| -                 | -                                                                  |
| `base/`           | source code for the Base module (part of Julia's standard library) |
| `stdlib/`         | source code for other standard library packages                    |
| `cli/`            | source for the command line interface/REPL                         |
| `contrib/`        | editor support for Julia source, miscellaneous scripts             |
| `deps/`           | external dependencies                                              |
| `doc/src/manual/` | source for the user manual                                         |
| `doc/build/`      | detailed notes for building Julia                                  |
| `src/`            | source for Julia language core                                     |
| `test/`           | test suites                                                        |
| `usr/`            | binaries and shared libraries loaded by Julia's standard libraries |

## Terminal, Editors and IDEs

The Julia REPL is quite powerful. See the section in the manual on
[the Julia REPL](https://docs.julialang.org/en/v1/stdlib/REPL/)
for more details.

On Windows we highly recommend running Julia in a modern terminal,
such as [Windows Terminal from the Microsoft Store](https://aka.ms/terminal).

Support for editing Julia is available for many
[widely used editors](https://github.com/JuliaEditorSupport):
[Emacs](https://github.com/JuliaEditorSupport/julia-emacs),
[Vim](https://github.com/JuliaEditorSupport/julia-vim),
[Sublime Text](https://github.com/JuliaEditorSupport/Julia-sublime), and many
others.

Supported IDEs include: [julia-vscode](https://github.com/JuliaEditorSupport/julia-vscode) (VS
Code plugin), [Juno](http://junolab.org/) (Atom plugin). [Jupyter](https://jupyter.org/)
notebooks are available through the [IJulia](https://github.com/JuliaLang/IJulia.jl) package, and
[Pluto](https://github.com/fonsp/Pluto.jl) notebooks through the Pluto.jl package.