diff options
Diffstat (limited to 'research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/creating-packages.md')
| -rw-r--r-- | research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/creating-packages.md | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/creating-packages.md b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/creating-packages.md new file mode 100644 index 0000000..a21887c --- /dev/null +++ b/research/flossing/external/julia-1.6.7/share/julia/stdlib/v1.6/Pkg/docs/src/creating-packages.md @@ -0,0 +1,290 @@ +# **5.** Creating Packages + +A package is a project with a `name`, `uuid` and `version` entry in the `Project.toml` file, and a `src/PackageName.jl` file that defines the module `PackageName`. +This file is executed when the package is loaded. + +### Generating files for a package + +!!! note + The [PkgTemplates](https://github.com/invenia/PkgTemplates.jl) package offers a very easy, repeatable, and + customizable way to generate the files for a new package. We recommend that you use PkgTemplates for creating + new packages instead of using the minimal `pkg> generate` functionality described below. + +To generate files for a new package, use `pkg> generate`. + +```julia-repl +(v1.0) pkg> generate HelloWorld +``` + +This creates a new project `HelloWorld` with the following files (visualized with the external [`tree` command](https://linux.die.net/man/1/tree)): + +```julia-repl +julia> cd("HelloWorld") + +shell> tree . +. +├── Project.toml +└── src + └── HelloWorld.jl + +1 directory, 2 files +``` + +The `Project.toml` file contains the name of the package, its unique UUID, its version, the authors and potential dependencies: + +```toml +name = "HelloWorld" +uuid = "b4cd1eb8-1e24-11e8-3319-93036a3eb9f3" +version = "0.1.0" +authors = ["Some One <someone@email.com>"] + +[deps] +``` + +The content of `src/HelloWorld.jl` is: + +```julia +module HelloWorld + +greet() = print("Hello World!") + +end # module +``` + +We can now activate the project and load the package: + +```julia-repl +pkg> activate . + +julia> import HelloWorld + +julia> HelloWorld.greet() +Hello World! +``` + +### Adding dependencies to the project + +Let’s say we want to use the standard library package `Random` and the registered package `JSON` in our project. +We simply `add` these packages (note how the prompt now shows the name of the newly generated project, +since we `activate`d it): + +```julia-repl +(HelloWorld) pkg> add Random JSON + Resolving package versions... + Updating "~/Documents/HelloWorld/Project.toml" + [682c06a0] + JSON v0.17.1 + [9a3f8284] + Random + Updating "~/Documents/HelloWorld/Manifest.toml" + [34da2185] + Compat v0.57.0 + [682c06a0] + JSON v0.17.1 + [4d1e1d77] + Nullables v0.0.4 + ... +``` + +Both `Random` and `JSON` got added to the project’s `Project.toml` file, and the resulting dependencies got added to the `Manifest.toml` file. +The resolver has installed each package with the highest possible version, while still respecting the compatibility that each package enforces on its dependencies. + +We can now use both `Random` and `JSON` in our project. Changing `src/HelloWorld.jl` to + +```julia +module HelloWorld + +import Random +import JSON + +greet() = print("Hello World!") +greet_alien() = print("Hello ", Random.randstring(8)) + +end # module +``` + +and reloading the package, the new `greet_alien` function that uses `Random` can be called: + +```julia-repl +julia> HelloWorld.greet_alien() +Hello aT157rHV +``` + +### Adding a build step to the package + +The build step is executed the first time a package is installed or when explicitly invoked with `build`. +A package is built by executing the file `deps/build.jl`. + +```julia-repl +julia> print(read("deps/build.jl", String)) +println("I am being built...") + +(HelloWorld) pkg> build + Building HelloWorld → `deps/build.log` + Resolving package versions... + +julia> print(read("deps/build.log", String)) +I am being built... +``` + +If the build step fails, the output of the build step is printed to the console + +```julia-repl +julia> print(read("deps/build.jl", String)) +error("Ooops") + +(HelloWorld) pkg> build + Building HelloWorld → `deps/build.log` + Resolving package versions... +┌ Error: Error building `HelloWorld`: +│ ERROR: LoadError: Ooops +│ Stacktrace: +│ [1] error(::String) at ./error.jl:33 +│ [2] top-level scope at none:0 +│ [3] include at ./boot.jl:317 [inlined] +│ [4] include_relative(::Module, ::String) at ./loading.jl:1071 +│ [5] include(::Module, ::String) at ./sysimg.jl:29 +│ [6] include(::String) at ./client.jl:393 +│ [7] top-level scope at none:0 +│ in expression starting at /Users/kristoffer/.julia/dev/Pkg/HelloWorld/deps/build.jl:1 +└ @ Pkg.Operations Operations.jl:938 +``` + +### Adding tests to the package + +When a package is tested the file `test/runtests.jl` is executed: + +```julia-repl +julia> print(read("test/runtests.jl", String)) +println("Testing...") + +(HelloWorld) pkg> test + Testing HelloWorld + Resolving package versions... +Testing... + Testing HelloWorld tests passed +``` + +Tests are run in a new Julia process, where the package itself, and any +test-specific dependencies, are available, see below. + +#### Test-specific dependencies in Julia 1.2 and above + +!!! compat "Julia 1.2" + This section only applies to Julia 1.2 and above. For specifying test dependencies + on previous Julia versions, see [Test-specific dependencies in Julia 1.0 and 1.1](@ref). + +!!! note + The exact interaction between `Project.toml`, `test/Project.toml` and their corresponding + `Manifest.toml`s are not fully worked out, and may be subject to change in future versions. + The old method of adding test-specific dependencies, described in the next section, will + therefore be supported throughout all Julia 1.X releases. + +In Julia 1.2 and later the test environment is given by `test/Project.toml`. Thus, when running +tests, this will be the active project, and only dependencies to the `test/Project.toml` project +can be used. Note that Pkg will add the tested package itself implictly. + +!!! note + If no `test/Project.toml` exists Pkg will use the old style test-setup, as + described in [Test-specific dependencies in Julia 1.0 and 1.1](@ref). + +To add a test-specific dependency, i.e. a dependency that is available only when testing, +it is thus enough to add this dependency to the `test/Project.toml` project. This can be +done from the Pkg REPL by activating this environment, and then use `add` as one normally +does. Lets add the `Test` standard library as a test dependency: + +```julia-repl +(HelloWorld) pkg> activate ./test +[ Info: activating environment at `~/HelloWorld/test/Project.toml`. + +(test) pkg> add Test + Resolving package versions... + Updating `~/HelloWorld/test/Project.toml` + [8dfed614] + Test + Updating `~/HelloWorld/test/Manifest.toml` + [...] +``` + +We can now use `Test` in the test script and we can see that it gets installed when testing: + +```julia-repl +julia> print(read("test/runtests.jl", String)) +using Test +@test 1 == 1 + +(HelloWorld) pkg> test + Testing HelloWorld + Resolving package versions... + Updating `/var/folders/64/76tk_g152sg6c6t0b4nkn1vw0000gn/T/tmpPzUPPw/Project.toml` + [d8327f2a] + HelloWorld v0.1.0 [`~/.julia/dev/Pkg/HelloWorld`] + [8dfed614] + Test + Updating `/var/folders/64/76tk_g152sg6c6t0b4nkn1vw0000gn/T/tmpPzUPPw/Manifest.toml` + [d8327f2a] + HelloWorld v0.1.0 [`~/.julia/dev/Pkg/HelloWorld`] + Testing HelloWorld tests passed``` +``` + +#### Test-specific dependencies in Julia 1.0 and 1.1 + +!!! note + The method of adding test-specific dependencies described in this section will + be replaced by the method from the previous section in future Julia versions. + The method in this section will, however, be supported throughout all Julia 1.X + releases. + +In Julia 1.0 and Julia 1.1 test-specific dependencies are added to the main +`Project.toml`. To add `Markdown` and `Test` as test-dependencies, add the following: + +```toml +[extras] +Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a" +Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40" + +[targets] +test = ["Markdown", "Test"] +``` + +### Package naming guidelines + +Package names should be sensible to most Julia users, *even to those who are not domain experts*. +The following guidelines applies to the `General` registry, but may be useful for other package +registries as well. + +Since the `General` registry belongs to the entire community, people may have opinions about +your package name when you publish it, especially if it's ambiguous or can be confused with +something other than what it is. Usually you will then get suggestions for a new name that +may fit your package better. + +1. Avoid jargon. In particular, avoid acronyms unless there is minimal possibility of confusion. + + * It's ok to say `USA` if you're talking about the USA. + * It's not ok to say `PMA`, even if you're talking about positive mental attitude. +2. Avoid using `Julia` in your package name or prefixing it with `Ju`. + + * It is usually clear from context and to your users that the package is a Julia package. + * Package names already have a `.jl` extension, which communicates to users that `Package.jl` is a Julia package. + * Having Julia in the name can imply that the package is connected to, or endorsed by, contributors + to the Julia language itself. +3. Packages that provide most of their functionality in association with a new type should have pluralized + names. + + * `DataFrames` provides the `DataFrame` type. + * `BloomFilters` provides the `BloomFilter` type. + * In contrast, `JuliaParser` provides no new type, but instead new functionality in the `JuliaParser.parse()` + function. +4. Err on the side of clarity, even if clarity seems long-winded to you. + + * `RandomMatrices` is a less ambiguous name than `RndMat` or `RMT`, even though the latter are shorter. +5. A less systematic name may suit a package that implements one of several possible approaches to + its domain. + + * Julia does not have a single comprehensive plotting package. Instead, `Gadfly`, `PyPlot`, `Winston` + and other packages each implement a unique approach based on a particular design philosophy. + * In contrast, `SortingAlgorithms` provides a consistent interface to use many well-established + sorting algorithms. +6. Packages that wrap external libraries or programs should be named after those libraries or programs. + + * `CPLEX.jl` wraps the `CPLEX` library, which can be identified easily in a web search. + * `MATLAB.jl` provides an interface to call the MATLAB engine from within Julia. +7. Avoid naming a package closely to an existing package + * `Websocket` is too close to `WebSockets` and can be confusing to users. Rather use a new name such as `SimpleWebsockets`. + +### Registering packages + +Once a package is ready it can be registered with the [General Registry](https://github.com/JuliaRegistries/General). +Currently packages are submitted via [`Registrator`](https://juliaregistrator.github.io/). +In addition to `Registrator`, [`TagBot`](https://github.com/apps/julia-tagbot) helps manage the process of tagging releases. |