So are you ready ? Do you have every software you need ? (browser and notepad)
So now we will start to practice ! We will create and save our very first webpage !!!!
So let's start ! Now that we have everything we need let's open our notepad !
How about a little try. Let's write something whatever comes to your mind :)
You can really write whatever you want, the only goal is to have something written there.
Now that you have your text written it is time to save is and that's super easy just go on File and then Save.
A dialogue will now open and ask you where to save it, just choose a place and rename your file to what you want and end it by .html
Look at the picture below where we called our page as first.html:
Now if you open your file explorer you will see your page
Once you see this file we can open it up ! To do so just double click on it !
Indeed you saw it too !
Well actually to write a web page we can't just type text as we did. More to this text we also need to write what we call tags, those ones will give some instructions to the computer like "go to the next line" or "add an image"
So this would be too easy, of course some engineer had to come along and complicate everything. It's not enough to just write text in the editor you also need to give instructions to the computer and this is why we have tags.
HTML pages are full of what we call tags, they are invisible on the screen for your visitors but they allow to the computer what he needs to show.
Those tags can be spotted easily. They are surrounded with chevron, which means < and > like the following: <tag>
They indicate the nature of the text they surround. They mean for instance "this is a title" "this is an image" etc
We distinguish two kinds of tags the paired ones and the orphan one
They open contain texts and are closed later on, here is an example:
<title>This is a text</title>
We distinguish the opening tag <title> and the closing one </title> that indicates that the title is finished, this tells the computer that everything that is not in this tage is not a title
Exemple: this is not a title <title>this is a title</title> this is not a title
Those are the tags that serve usually to add an element at a specific place like an image.
It is not necessary to state the begining and end of an image we will just say to the computer that we want an image here
We use an orphan tag as follow:
<image />
The attributes are like options for a tag, they come to complete them and to give more informations to the computer, the attribute comes after the tag name and usually has a value: <tag attribute="value"...
Let's take our tag <image/> that we just saw, by itself it's not useful but we could add an attribute
that would indicate the name of the image to show: <image name="picture.jpg"/>
The computer then understands that he needs to show the image that is located in the file picture.jpg
In the case of a paired tag the attributes needs to be placed in the opening tag
Let's go back to our notepad and please type in there the same thing as there is on the picture below, which correspond to the basics of any HTML page:
There is some spaces at the begining of the lines to shift away some tags, this is not mandatory and won't change your page at the end but it makes the code easier to read, we call this indenting a page so you just need to press tab to do so in your text editor
You can see that the tags are opened and closed in a specific order.
For instance the  tag is the first to be opened and the last one to be closed (at the very end of the code with ).
The tags must be closed on the oposite way of there opening for instance:
Of course let's explain the diferent ones
<!DOCTYPE html>
The first line is called the doctype.
It is mandatory because that's the one that indicates that we are here creating an html page
This is not really a tag like the others (it starts with an exclamation mark).
We can say that its an exception that confirms a rule ;)
This is the main tag of the code, it frames up the whole code as you can see the closing tag is at the very end of the code
A web page is composed of two parts:
For now the body is empty (we will see that later). Let's focus on the two other tags in the head.
<meta charset="utf-8" />
This tag indicates the kind of encoding used in your .html file
Not going into much details here because it could get complicated really fast. The encoding indicates the way that the file is saved. It determines how the special characters will be displayed (accents, chinese symbols…)
Even though there is a lot of diferent encoding we can use nowadays most of the developers use utf-8 it can display almost all possible characters and that's why we will use it here
<title>
This is the title of your page, maybe the most important element!
Every page must have a title that describes what it contains, it's advised to use short titles less then a 100 characters
The title won't be displayed on the page itself but on the tab as described in the picture below
We learnt how to create our first real html page in that chapter.
Before we finish i would like to present you the concept of the comments
A comment in html is a text that is used as a note or a remainder.
It is not displayed, it's not read by the computer it doesn't change anything to the page display
Of course it is !
It is useful to you and to the persons that will read the source code of your page.
You can leave some comments to have some indications on how your page works
It will help you remember how your page is working if you come back to your code after a long time.
A comment is a special html tag:

You can put it anywhere you want in your code there is no impact in the way the page is displayed but you can use it for instance to remember where you are in your code especially if it is a long code !
You can easily test this see this in every webpage because the browser has to dispaly the html every html page is public.
End of the story, everybody can see your html code and there is nothing you can do to stop them, so don't put there important information like passwords in comments ;)
So create a clean code easy to understand ! For you and others !
So now we have a white page its very nice but not very useful so here we will discover some of the basic tags that every developer needs to know
Most of the time when we write texts on a webpage we do it in paragraphs so in html a tag was created with this purpose specifically and it is

 hi welcome on my website

 signifies the begining of the paragraph and
 the end of it
As said previously we need to add this tag inside our tag  so it will be displayed your page should look like this:
It's important to notice that we can' go to a new line just pressing enter to do so we need to use a special tag
 this explains to the brower that the text must start on a newline now.
The
 tag is an orphan tag and can be placed inside paragraphs
Now let's see another tag:
As anywhere we use titles and titles can have diferent importance for instance in a book the title of the book won't be the same as the title of the chapters, to achieve this in html we defined six diferent levels of importance:

the bigger title
 …………..
title really REALLY not important at all

In practice those six levels are rarely used we most importantly use

 those are generally enough :)
You can try it out on a page like the one below
That's a page that is starting to look like stomething !!
For this you should check section two of this webquest and start using css ! ;)
Let's sum up what we have seen so far:


Knockout! Watch Jason Knight end Artem Lobov in one-sided rematch at Bare Knuckle FC 9
by Dan HiergesellJason Knight got the revenge he was looking for last night (Sat., Nov. 16, 2019) at Bare Knuckle FC 9 live on FITE.TV PPV from Biloxi, Mississippi, when he battered fellow UFC veteran Artem Lobov in their main event rematch en route to claiming a bloody fifth-round knockout finish.
From the looks of the first fight you would think both fighters were going to land shots in last night’s rematch, but that simply wasn’t the case. Knight was able to tighten up his punches, lean on his precision, and utilize his range to put “Russian Hammer” out of service.
Knight’s efforts paid off throughout the fight as Conor McGregor’s main man suffered cuts to his face and a knockdown in the second, but Lobov kept plodding forward. That was until Knight landed a final left hand to Lobov’s eye in the fifth round and forced the Russian to fall to the canvas in pain.
Check out the highlights below:
Stick with Mania for additional BKFC 9: ‘Lobov vs. Knight 2’ reaction.


Reset Your Password
Email address
New Password
Confirm New Password
Submit
Loading..
Success!
Please check your e-mail.


--- title: Class List navLabel: List category: class body_class: dark ---
Add an entry to the end of the list
entry_
- The entry to add to the listAdd an entry at a certain index into the list
entry_
- The entry to add to the listindex
- The index to add the entry toAdds a Listener that will notify you if a Discard, Delete or Error event occurs
recordEventsListener
- The listener to addDiscard the List. This should be called whenever you are done with the List retrieved by RecordHandler .getList(String)
. This does not
guarantee that your subscriptions have been unsubscribed, so make sure to do that first!
If all usages of the same List have been discarded, the List will no longer be updated from the server and any further usages will require the List to be retrieved again via RecordHandler .getList(String)
Returns the array of list entries or an empty array if the list hasn’t been populated yet.
Return whether the list has been destroyed. If true and you need to use the method create it again via
RecordHandler .getList(String)
(String)}
Returns true if the list is empty
Return whether the list data has been loaded from the server
Return the list name
Removes the first occurrence of an entry from the list
entry_
- The entry to remove from the listRemoves an entry from the list if it resides at a specific index
entry_
- The entry to remove from the listindex
- The index at which the entry should reside atRemove listener added via List.addRecordEventsListener (RecordEventsListener )
recordEventsListener
- The listener to removeUpdates the list with a new set of entries
entries
- The recordNames to update the list withNotifies the user whenever the list has changed
listChangedListener
- The listener to addNotifies the user whenever the list has changed, and notifies immediately if triggerNow is true
listChangedListener
- The listener to addtriggerNow
- Whether to trigger the listener immediatelyNotifies the user whenever the list has changed
listEntryChangedListener
- The listener to addRemoves the listener added via List.subscribe(ListChangedListener,boolean)
listChangedListener
- The listener to removeRemoves the listener added via List.subscribe(ListChangedListener,boolean)
listEntryChangedListener
- The listener to removeReturn the list version. This is solely used within a RecordMergeStrategy
.
Constructor is not public since it is created via RecordHandler .getList(String)
recordHandler
- The recordHandler to get the underlying recordname
- The list
nameReturns the underlying record, used with the ready handler to allow the API to be sync
Returns the array of list entries or an empty array if the list hasn’t been populated yet.
Useful entry point for diffing previous list and new one to get entries added, removed and moved
Establishes the current structure of the list, provided the client has attached any add / move / remove listener This will be called before any change to the list, regardsless if the change was triggered by an incoming message from the server or by the client
Compares the structure of the list after a change to its previous structure and notifies any add / move / remove listener. Won’t do anything if no listeners are attached.
Iterates through the list and creates a map with the entry as a key and an array of its position(s) within the list as a value, e.g . { ‘recordA’: [ 0, 3 ], ‘recordB’: [ 1 ], ‘recordC’: [ 2 ] }


Guild Member Grey:
Welcome, my hunter brother. What can I do for you?
"Is there any work?"
"I wish to test for the 2-circle hunter license."
"I wish to leave the Hunters Guild."


Add simple user feedback widget to any page.
HQ has a custom feedback component that uses Knockout Components. See feedback.js for full documentation.
{% include 'styleguide/example_html.html' with slug='feedback' title='Feedback' content=examples.feedback %}


Welcome,
Manager
Request Detail
Discovery Request 2017-111222
Tasks
| Task Number | Assigned To | # of Items | Difficulty Rating | PDue Date | Status | Completed Date |
|---|---|---|---|---|---|---|
| 1234 | Mimi Badgerow | 2 | 2 | 023.01.2018 | Complete | 02.20.2018 |
| 4321 | Shawna Rohr | 2 | 4 | 03.01.2018 | Waiting on Others |
Additional Details
Matter Name
Matter Number
Assignment Date
02.05.2018
Paralegal Assigned
Shawna Rohr


Hack4Progress is all about technology and social good.
Here at Hack4Progress, we provide software and hardware support for other nonprofits, activists, and social workers who need assistance.
We also provide Raspberry Pi computers and programming tutoring for youth to provide young scholars the tools to embark on a career in the tech-world.
Who We Are
Hack4Progress was founded by Alexander Tekle in May of 2015 with simply a motive to combine the immense ability of software and hardware to empower the community and world around him.


Sign In
Register
Sign In
Welcome to Drikimages!
Username
Password
Remember Me
Forgot Password
Log In
————— OR SIGN IN WITH —————
Login with Facebook
Login with Google
Register
New to Drikimages Images?
First Name
Last Name
User Type
Client
Contributor
Company name (optional)
Job title
(optional)
Email Address
Password
Log In


Hello mobile world!
Open Dlg
Pop-Up Dialog
I am a dialog field and should have a close button above, see
jQuery Mobile examples


Tutorial¶
This tutorial will guide through the creation and analysis of a superconducting circuit with CircuitQ. It shows some of the core functionalities of CircuitQ and demonstrates how to use them. While the variety of possible input circuits is high, we will here focus on the Fluxonium as an example.
Import statements¶
First, import circuitq
and networkx
. The latter toolbox is required to construct the circuit graph.
[1]:
import circuitq as cq
import networkx as nx
It is also convenient to import numpy
for the use of numerical expressions and pyplot
to visualize some results.
[2]:
import numpy as np
import matplotlib.pyplot as plt
Create circuit graph¶
A superconducting circuit can be related to a graph by relating all circuit elements between two nodes to an edge of the graph. Possible elements are capacitances ('C'
), linear inductances ('L'
) and Josephson junctions ('J'
).
Since multiple edges of such a graph can be in parallel we work with the MultiGraph
class of networkx
.
Let’s consider the Fluxonium as an example, which consists of a linear inductance and a Josephson junction in parallel together with a shunted capacity.
To initialize the circuit, we execute the following:
[3]:
graph = nx.MultiGraph()
graph.add_edge(0,1, element = 'C')
graph.add_edge(0,1, element = 'J')
graph.add_edge(0,1, element = 'L')
circuit = cq.CircuitQ(graph)
Here, we created a graph with three elements in between node 0 and node 1. The CircuitQ
class is the core of the toolbox. An element of this class corresponds to a superconducting circuit. Ground nodes and charge offset nodes can be specified upon initialization. Please refer to the API reference for more details.
CircuitQ’s function visualize_circuit_general()
can be used to visualize the graph.
Symbolic Hamiltonian¶
CircuitQ performs an automated quantization of the input circuit. It provides a symbolic SymPy
expression for the corresponding circuit Hamiltonian.
[4]:
circuit.h
[4]:
Parameters¶
Besides the flux and charge variables \(\phi\) and \(q\), the Hamiltonian contains system parameters, whose values can be changed to tune the circuit.
[5]:
circuit.h_parameters
[5]:
[C_{01}, E_{J010}, L_{010}, \tilde{\Phi}_{010}]
In this case it contains the capacity \(C_{01}\), the Josephson energy \(E_{J010}\) and the inductance \(L_{010}\). During quantization, CircuitQ automatically detects inductive loops and assigns loop fluxes to them, which is represented by \(\tilde{\Phi}_{010}\). If a charge offset would have been assigned upon initialization, it would also appear as a parameter \(qo\).
Let’s assign a numerical value for the Josephson energy and the external flux
[6]:
EJ = circuit.c_v["E"]/3
phi_ext = np.pi*circuit.phi_0
circuit.c_v
is a dictionary for characteristic parameter values. circuit.phi_0
is the flux quantum, which we define as \(\Phi_o = \frac{\hbar}{2e}\).
Numerical Hamiltonian¶
To analyze the circuit’s quantum physical properties, a numerical representation of the Hamiltonian has to be generated.
[7]:
h_num = circuit.get_numerical_hamiltonian(401,
parameter_values=[False, EJ, False, phi_ext ])
The method get_numerical_hamiltonian()
takes the length of the matrices representing the flux and charge variables as the first parameter input (here 401
). CircuitQ automatically performs the numerical implementation of the node variables either in the charge basis, in the flux basis or also in a combination of both - depending on the periodicity of the potential along the individual flux variables. In the exemplary case of the Fluxonium, the flux basis will be used due to the harmonic
contribution of the linear inductance. The length of the numerical flux coordinate grid can be set manually by using the keyword grid_length
. This may have a crucial impact on the numerical results. If it is not specified (like in the example above) it is set to the default value \(\Phi_{max} = 4 \pi \Phi_o\). For the cases which are implemented in the charge basis, CircuitQ
’s method transform_charge_to_flux()
can be used to be able to express the eigenstates still in the flux
basis (see More Examples -> Flux Qubit).
To assign specific parameter values, use an input list for paramter_values
, with the same order as the h_parameters
list. If a value is set to False
, a characteristic default value will be assigned to it.
The numerical Hamiltonian is represented as a sparse csr_matrix
from the SciPy
package.
Diagonalization¶
To get the (lowest) eigenvalues and eigenstates of the numerical Hamiltonian, use get_eigensystem()
which is a wrapper around SciPy
’s eigsh
function for sparse matrices.
[8]:
eigv, eigs = circuit.get_eigensystem()
Finally, we can plot the lowest eigenstates of the circuit.
[9]:
h = 6.62607015e-34
y_scaling = 1/(h *1e9)
plt.plot(circuit.flux_list, np.array(circuit.potential)*y_scaling, lw=1.5)
for n in range(5):
plt.plot(circuit.flux_list,
(eigv[n]+ abs(eigs[:,n])**2*2e-23)*y_scaling
,label="Eigenstate " +str(n))
plt.legend()
plt.xlabel(r"$\Phi_1 / \Phi_o$")
plt.ylabel(r"Energy in GHz$\cdot$h")
plt.xticks(np.linspace(-2*np.pi, 1*np.pi, 4)*circuit.phi_0 ,
[r'$-2\pi$', r'$-\pi$',r'$0$',r'$\pi$'])
plt.xlim(-2.5*np.pi*circuit.phi_0, 1.5*np.pi*circuit.phi_0)
plt.ylim(1,10)
plt.show()
To plot the potential, the potential
attribute of a CircuitQ
instance can be used if the problem is 1-dimensional and formulated in flux basis.
Anharmonicity¶
To operate the circuit as a qubit, a certain degree of the spectrum’s anharmonicity is desired. CircuitQ provides a measure for this purpose, which can be given by get_spectrum_anharmonicity()
. The method considers the transition that is the closest to the qubit transition and subsequently calculates the quotient between these two transitions and returns abs(1-quotient). A cutoff has been implemented, such that the returned anharmonicity is within \([0,1]\).
[10]:
circuit.get_spectrum_anharmonicity()
[10]:
1
\(T1\) time¶
The robustness against decoherence is a crucial property of a circuit. For this purpose, we developed three measures to evaluate the \(T1\) time contribution due to quasiparticle tunneling,
[11]:
T1_qp = circuit.get_T1_quasiparticles()
print("Quasiparticles noise contribution T1 = {:e} s".format(T1_qp))
Quasiparticles noise contribution T1 = 2.272398e-05 s
charge noise,
[12]:
T1_c = circuit.get_T1_charge()
print("Charge noise contribution T1 = {:e} s".format(T1_c))
Charge noise contribution T1 = 1.891442e-04 s
and flux noise
[13]:
T1_f = circuit.get_T1_flux()
print("Flux noise contribution T1 = {:e} s".format(T1_f))
Flux noise contribution T1 = 1.895929e-02 s
This leads to an overall \(T1\) time measure of:
[14]:
print("Total T1 = {:e} s".format( 1/( 1/T1_qp + 1/T1_c + 1/T1_f)))
Total T1 = 2.026503e-05 s
Please refer to our preprint for more details on how the noise contributions are calculated.
Parameter sweep¶
The dependence of circuit properties on the value of one or more parameters is a crucial aspect to consider when analysing superconducting circuits.
The exemplary spectrum above depends on the value of the external flux \(\tilde{\Phi}_{010}\). For the previous plot, we have chosen the external flux to be \(\pi \cdot \Phi_o\). If we set this value to \(0\), the spectrum has the following form:
[15]:
phi_ext = 0
circuit.get_numerical_hamiltonian(401, parameter_values=[False, EJ, False, phi_ext ])
eigv, eigs = circuit.get_eigensystem()
plt.plot(circuit.flux_list, np.array(circuit.potential)*y_scaling, lw=1.5)
for n in range(5):
plt.plot(circuit.flux_list,
(eigv[n]+ abs(eigs[:,n])**2*2e-23)*y_scaling
,label="Eigenstate " +str(n))
plt.legend()
plt.xlabel(r"$\Phi_1 / \Phi_o$")
plt.ylabel(r"Energy in GHz$\cdot$h")
plt.xticks(np.linspace(-2*np.pi, 2*np.pi, 5)*circuit.phi_0 ,
[r'$-2\pi$', r'$-\pi$',r'$0$',r'$\pi$',r'$2\pi$'])
plt.xlim(-2.5*np.pi*circuit.phi_0, 2.5*np.pi*circuit.phi_0)
plt.ylim(-5,20)
plt.show()
The harmonicity of the spectrum increased due to the change of the external flux. This fact will also be reflected when calculating the anahrmonicity.
[16]:
circuit.get_spectrum_anharmonicity()
[16]:
0.05288147513284358
We can further study the dependence of the lowest eigenenergies as a function of the external flux.
Let’s start by calculating the eigenvalues for differnt values of the external flux. Note that the order of the paramter_values
list stays the same.
[17]:
eigenvalues = []
phi_ext_list = np.linspace(-2*np.pi*circuit.phi_0,2*np.pi*circuit.phi_0,100)
for phi_ext in phi_ext_list:
circuit.get_numerical_hamiltonian(401, parameter_values=[False, EJ, False, phi_ext])
eigv, eigs = circuit.get_eigensystem(5)
eigenvalues.append(eigv)
Finally, we can plot the parameter sweep.
[18]:
plt.plot(phi_ext_list, np.array(eigenvalues)*y_scaling)
plt.xlabel(r"External Flux $ \tilde{\Phi}_{010} / \Phi_o$")
plt.ylabel(r"Energy in GHz$\cdot$h")
plt.xticks(np.linspace(-2*np.pi, 2*np.pi, 5)*circuit.phi_0 ,
[r'$-2\pi$', r'$-\pi$',r'$0$',r'$\pi$',r'$2\pi$'])
plt.show()
We are not restricted in analyzing only the impact of the external flux, as this variation can be done for any parameter in paramter_values
.
Charge offset¶
The offset of a node charge can be tuned by an external source. To work with charge offsets, the corresponding nodes have to be specified when initializing a CircuitQ
instance. As a demonstration let’s choose node 1 to have a charge offset.
[19]:
circuit = cq.CircuitQ(graph, offset_nodes=[1])
circuit.h
[19]:
The node charge \(q_1\) is now shifted by an offset charge \(\tilde{q}_1\). This new variable now also appears in in the parameter list:
[20]:
circuit.h_parameters
[20]:
[C_{01}, E_{J010}, L_{010}, \tilde{\Phi}_{010}, \tilde{q}_{1}]
Finally, we can also study the impact of the external charge on the spectrum of the exemplary circuit.
[21]:
eigenvalues = []
phi_ext = np.pi*circuit.phi_0
q_off_list = np.linspace(-10*2*circuit.e,10*2*circuit.e,30)
for q_off in q_off_list:
circuit.get_numerical_hamiltonian(401,
parameter_values=[False, EJ, False, phi_ext, q_off])
eigv, eigs = circuit.get_eigensystem(5)
eigenvalues.append(eigv)
plt.plot(q_off_list/(2*circuit.e), np.array(eigenvalues)*y_scaling)
plt.xlabel(r"Charge offset $\tilde{q}_1 / (2e)$")
plt.ylabel(r"Energy in GHz$\cdot$h")
plt.show()


Canopy Growth names veteran Constellation executive David Klein as new CEO
SMITH FALLS, Ont. — Canopy Growth Corp. has named a veteran Constellation Brands executive as its new chief executive.
by Canadian PressSMITH FALLS, Ont. — Canopy Growth Corp. has named a veteran Constellation Brands executive as its new chief executive.
The cannabis company says David Klein, the chief financial officer at Canopy's largest shareholder, will replace Mark Zekulin, effective Jan. 14, 2020.
Klein has been serving as chairman of the board at Canopy, which intends to appoint a new chair once he takes over as CEO.
Zekulin is a founding employee at Canopy and served in a variety of roles including president, then president and co-CEO, and finally as CEO after co-founder Bruce Linton was ousted earlier this year.
Linton's departure came after Constellation said in June that it was "not pleased" with the company's financial results.
Zekulin is expected to step down as CEO and resign his seat on the board of directors of Canopy effective Dec. 20.
This report by The Canadian Press was first published Dec. 9, 2019.
Companies in this story: (TSX:WEED)
The Canadian Press


Returns a linear prediction Tensor
based on given feature_columns
.
tf.compat.v1.feature_column.linear_model( features, feature_columns, units=1, sparse_combiner='sum', weight_collections=None, trainable=True, cols_to_vars=None )
This function generates a weighted sum based on output dimension units
.
Weighted sum refers to logits in classification problems. It refers to the
prediction itself for linear regression problems.
Note on supported columns: linear_model
treats categorical columns as
indicator_column
s. To be specific, assume the input as SparseTensor
looks
like:
shape = [2, 2] { [0, 0]: "a" [1, 0]: "b" [1, 1]: "c" }
linear_model
assigns weights for the presence of "a", "b", "c' implicitly,
just like indicator_column
, while input_layer
explicitly requires wrapping
each of categorical columns with an embedding_column
or an
indicator_column
.
price = numeric_column('price') price_buckets = bucketized_column(price, boundaries=[0., 10., 100., 1000.]) keywords = categorical_column_with_hash_bucket("keywords", 10K) keywords_price = crossed_column('keywords', price_buckets, ...) columns = [price_buckets, keywords, keywords_price ...] features = tf.io.parse_example(..., features=make_parse_example_spec(columns)) prediction = linear_model(features, columns)
The sparse_combiner
argument works as follows
For example, for two features represented as the categorical columns:
# Feature 1 shape = [2, 2] { [0, 0]: "a" [0, 1]: "b" [1, 0]: "c" } # Feature 2 shape = [2, 3] { [0, 0]: "d" [1, 0]: "e" [1, 1]: "f" [1, 2]: "f" }
with sparse_combiner
as "mean", the linear model outputs consequently
are:
y_0 = 1.0 / 2.0 * ( w_a + w_b ) + w_d + b y_1 = w_c + 1.0 / 3.0 * ( w_e + 2.0 * w_f ) + b
where y_i
is the output, b
is the bias, and w_x
is the weight
assigned to the presence of x
in the input features.
features
: A mapping from key to tensors. _FeatureColumn
s look up via these
keys. For example numeric_column('price')
will look at 'price' key in
this dict. Values are Tensor
or SparseTensor
depending on
corresponding _FeatureColumn
.feature_columns
: An iterable containing the FeatureColumns to use as inputs
to your model. All items should be instances of classes derived from
_FeatureColumn
s.units
: An integer, dimensionality of the output space. Default value is 1.sparse_combiner
: A string specifying how to reduce if a categorical column
is multivalent. Except numeric_column
, almost all columns passed to
linear_model
are considered as categorical columns. It combines each
categorical column independently. Currently "mean", "sqrtn" and "sum" are
supported, with "sum" the default for linear model. "sqrtn" often achieves
good accuracy, in particular with bag-of-words columns.weight_collections
: A list of collection names to which the Variable will be
added. Note that, variables will also be added to collections
tf.GraphKeys.GLOBAL_VARIABLES
and ops.GraphKeys.MODEL_VARIABLES
.trainable
: If True
also add the variable to the graph collection
GraphKeys.TRAINABLE_VARIABLES
(see tf.Variable
).cols_to_vars
: If not None
, must be a dictionary that will be filled with a
mapping from _FeatureColumn
to associated list of Variable
s. For
example, after the call, we might have cols_to_vars = {
_NumericColumn(
key='numeric_feature1', shape=(1,):
[A Tensor
which represents predictions/logits of a linear model. Its shape
is (batch_size, units) and its dtype is float32
.
ValueError
: if an item in feature_columns
is neither a _DenseColumn
nor _CategoricalColumn
.


Elastic Load Balancing V2 Actions
Actions
is a property of the AWS::ElasticLoadBalancingV2::ListenerRule resource that specifies the actions an Elastic Load Balancing listener takes when
an incoming request meets a listener rule's condition.
Syntax
JSON
{ "AuthenticateCognitoConfig" : AuthenticateCognitoConfig, "AuthenticateOidcConfig" : AuthenticateOidcConfig, "FixedResponseConfig" : FixedResponseConfig, "Order" :
Integer
, "RedirectConfig" : RedirectConfig, "TargetGroupArn" :String
, "Type" :String
}
YAML
AuthenticateCognitoConfig: AuthenticateCognitoConfig AuthenticateOidcConfig: AuthenticateOidcConfig FixedResponseConfig: FixedResponseConfig Order:
Integer
RedirectConfig: RedirectConfig TargetGroupArn:String
Type:String
Properties
AuthenticateCognitoConfig
-
[HTTPS listener] Information for using Amazon Cognito to authenticate users. Specify only when Type is
authenticate-cognito
.Required: No
Type: AuthenticateCognitoConfig
Update requires: No interruption
AuthenticateOidcConfig
-
[HTTPS listener] Information about an identity provider that is compliant with OpenID Connect (OIDC). Specify only when Type is
authenticate-oidc
.Required: No
Type: AuthenticateOidcConfig
Update requires: No interruption
FixedResponseConfig
-
[Application Load Balancer] Information for creating an action that returns a custom HTTP response. Specify only when Type is
fixed-response
.Required: No
Type: FixedResponseConfig
Update requires: No interruption
Order
-
The order for the action. This value is required for rules with multiple actions. The action with the lowest value for order is performed first. The final action to be performed must be a
forward
or afixed-response
action.Valid Range: Minimum value of 1. Maximum value of 50000.
Required: No
Type: Integer
Update requires: No interruption
RedirectConfig
-
[Application Load Balancer] Information for creating a redirect action. Specify only when Type is
redirect
.Required: No
Type: RedirectConfig
Update requires: No interruption
TargetGroupArn
-
The Amazon Resource Name (ARN) of the target group to which Elastic Load Balancing routes the traffic.
Required: Yes
Type: String
Type
-
The type of action.
Valid values:
forward
|authenticate-oidc
|authenticate-cognito
|redirect
|fixed-response
Required: Yes
Type: String


Vanilla UI
Hello!
I am modal 1 content. All should fear me.
Close modal 1
Oops!
Deadly Neurotoxin gas released!
Okay, cool
Open modal 1
Open modal 2


{% extends "base.html" %} {% block content %}
Instructions for: {{device.name}}
The settings to enable GPS tagging are different for different phones.
Continue to upload →


A chart contains a number of Kubernetes resources and components that work together. As a chart author, you may want to write some tests that validate that your chart works as expected when it is installed. These tests also help the chart consumer understand what your chart is supposed to do.
A test in a helm chart lives under the templates/
directory and is a pod definition that specifies a container with a given command to run. The container should exit successfully (exit 0) for a test to be considered a success. The pod definition must contain one of the helm test hook annotations: helm.sh/hook: test-success
or helm.sh/hook: test-failure
.
Example tests: - Validate that your configuration from the values.yaml file was properly injected. - Make sure your username and password work correctly - Make sure an incorrect username and password does not work - Assert that your services are up and correctly load balancing - etc.
You can run the pre-defined tests in Helm on a release using the command helm test <RELEASE_NAME>
. For a chart consumer, this is a great way to sanity check that their release of a chart (or application) works as expected.
In Helm, there are two test hooks: test-success
and test-failure
test-success
indicates that test pod should complete successfully. In other words, the containers in the pod should exit 0. test-failure
is a way to assert that a test pod should not complete successfully. If the containers in the pod do not exit 0, that indicates success.
Here is an example of a helm test pod definition in an example mariadb chart:
mariadb/
Chart.yaml
README.md
values.yaml
charts/
templates/
templates/tests/test-mariadb-connection.yaml
In wordpress/templates/tests/test-mariadb-connection.yaml
:
apiVersion: v1
kind: Pod
metadata:
name: "{{ .Release.Name }}-credentials-test"
annotations:
"helm.sh/hook": test-success
spec:
containers:
- name: {{ .Release.Name }}-credentials-test
image: {{ .Values.image }}
env:
- name: MARIADB_HOST
value: {{ template "mariadb.fullname" . }}
- name: MARIADB_PORT
value: "3306"
- name: WORDPRESS_DATABASE_NAME
value: {{ default "" .Values.mariadb.mariadbDatabase | quote }}
- name: WORDPRESS_DATABASE_USER
value: {{ default "" .Values.mariadb.mariadbUser | quote }}
- name: WORDPRESS_DATABASE_PASSWORD
valueFrom:
secretKeyRef:
name: {{ template "mariadb.fullname" . }}
key: mariadb-password
command: ["sh", "-c", "mysql --host=$MARIADB_HOST --port=$MARIADB_PORT --user=$WORDPRESS_DATABASE_USER --password=$WORDPRESS_DATABASE_PASSWORD"]
restartPolicy: Never
$ helm install mariadb
NAME: quirky-walrus
LAST DEPLOYED: Mon Feb 13 13:50:43 2017
NAMESPACE: default
STATUS: DEPLOYED
$ helm test quirky-walrus
RUNNING: quirky-walrus-credentials-test
SUCCESS: quirky-walrus-credentials-test
templates/
directorytests/
directory like <chart-name>/templates/tests/
for more isolation


---
layout: default
---
{% include fixed/blm.html %}
{% include fixed/section.html texts=site.data.home.fabevents %}
{% include fixed/section.html texts=site.data.home.ukraine %}
{% include fixed/section.html texts=site.data.home.M19 %}
{% include fixed/section.html texts=site.data.home.fablabs %}
{% include fixed/blue-questions.html texts=site.data.home.questions-audiences %}
{% include fixed/section.html texts=site.data.home.academany %}
{% include fixed/section.html texts=site.data.k-12.scopes-full %}
{% include fixed/section.html texts=site.data.home.projects %}
{% include customizable/section.html texts=site.data.home.teacher-award %}
{% include fixed/donations-alert.html texts=site.data.home.donate %}
{% include fixed/section.html texts=site.data.home.congress %}
{% include fixed/partners.html texts=site.data.home.partners %}
{% include fixed/banner.html texts=site.data.home.designing-reality %}


Job List
Job Category
Company List
Job Location
Job List
Job Category
Company List
Job Location
Search


5.1. Quickstart¶
Suppose that you are in a directory containing a single Cabal package which you wish to build (if you haven’t set up a package yet check out developing packages for instructions). You can configure and build it using Nix-style local builds with this command (configuring is not necessary):
$ cabal v2-build
To open a GHCi shell with this package, use this command:
$ cabal v2-repl
To run an executable defined in this package, use this command:
$ cabal v2-run <executable name> [executable args]
5.1.1. Developing multiple packages¶
Many Cabal projects involve multiple packages which need to be built
together. To build multiple Cabal packages, you need to first create a
cabal.project
file which declares where all the local package
directories live. For example, in the Cabal repository, there is a root
directory with a folder per package, e.g., the folders Cabal
and
cabal-install
. The cabal.project
file specifies each folder as
part of the project:
packages: Cabal/
cabal-install/
The expectation is that a cabal.project
is checked into your source
control, to be used by all developers of a project. If you need to make
local changes, they can be placed in cabal.project.local
(which
should not be checked in.)
Then, to build every component of every package, from the top-level directory, run the command: (using cabal-install-2.0 or greater.)
$ cabal v2-build
To build a specific package, you can either run v2-build
from the
directory of the package in question:
$ cd cabal-install
$ cabal v2-build
or you can pass the name of the package as an argument to
cabal v2-build
(this works in any subdirectory of the project):
$ cabal v2-build cabal-install
You can also specify a specific component of the package to build. For
example, to build a test suite named package-tests
, use the command:
$ cabal v2-build package-tests
Targets can be qualified with package names. So to request
package-tests
from the Cabal
package, use
Cabal:package-tests
.
Unlike sandboxes, there is no need to setup a sandbox or add-source
projects; just check in cabal.project
to your repository and
v2-build
will just work.
5.2. Cookbook¶
5.2.1. How can I profile my library/application?¶
Create or edit your cabal.project.local
, adding the following
line:
profiling: True
Now, cabal v2-build
will automatically build all libraries and
executables with profiling. You can fine-tune the profiling settings
for each package using profiling-detail
:
package p
profiling-detail: toplevel-functions
Alternately, you can call cabal v2-build --enable-profiling
to
temporarily build with profiling.
5.3. How it works¶
5.3.1. Local versus external packages¶
One of the primary innovations of Nix-style local builds is the distinction between local packages, which users edit and recompile and must be built per-project, versus external packages, which can be cached across projects. To be more precise:
- A local package is one that is listed explicitly in the
packages
,optional-packages
orextra-packages
field of a project. Usually, these refer to packages whose source code lives directly in a folder in your project (although, you can list an arbitrary Hackage package inextra-packages
to force it to be treated as local).
Local packages, as well as the external packages (below) which depend on them, are built inplace, meaning that they are always built specifically for the project and are not installed globally. Inplace packages are not cached and not given unique hashes, which makes them suitable for packages which you want to edit and recompile.
- An external package is any package which is not listed in the
packages
field. The source code for external packages is usually retrieved from Hackage.
When an external package does not depend on an inplace package, it can be built and installed to a global store, which can be shared across projects. These build products are identified by a hash that over all of the inputs which would influence the compilation of a package (flags, dependency selection, etc.). Just as in Nix, these hashes uniquely identify the result of a build; if we compute this identifier and we find that we already have this ID built, we can just use the already built version.
The global package store is ~/.cabal/store
(configurable via
global store-dir option); if you need to clear your store for
whatever reason (e.g., to reclaim disk space or because the global
store is corrupted), deleting this directory is safe (v2-build
will just rebuild everything it needs on its next invocation).
This split motivates some of the UI choices for Nix-style local build
commands. For example, flags passed to cabal v2-build
are only
applied to local packages, so that adding a flag to
cabal v2-build
doesn’t necessitate a rebuild of every transitive
dependency in the global package store.
In cabal-install 2.0 and above, Nix-style local builds also take advantage of a new Cabal library feature, per-component builds, where each component of a package is configured and built separately. This can massively speed up rebuilds of packages with lots of components (e.g., a package that defines multiple executables), as only one executable needs to be rebuilt. Packages that use Custom setup scripts are not currently built on a per-component basis.
5.3.2. Where are my build products?¶
A major deficiency in the current implementation of v2-build is that there is no programmatic way to access the location of build products. The location of the build products is intended to be an internal implementation detail of v2-build, but we also understand that many unimplemented features can only be reasonably worked around by accessing build products directly.
The location where build products can be found varies depending on the version of cabal-install:
- In cabal-install-1.24, the dist directory for a package
p-0.1
is stored indist-newstyle/build/p-0.1
. For example, if you built an executable or test suite namedpexe
, it would be located atdist-newstyle/build/p-0.1/build/pexe/pexe
. - In cabal-install-2.0, the dist directory for a package
p-0.1
defining a library built with GHC 8.0.1 on 64-bit Linux isdist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1
. When per-component builds are enabled (any non-Custom package), a subcomponent like an executable or test suite namedpexe
will be stored atdist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe
; thus, the full path of the executable isdist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/c/pexe/build/pexe/pexe
(you can see why we want this to be an implementation detail!) - In cabal-install-2.2 and above, the
/c/
part of the above path - is replaced with one of
/l/
,/x/
,/f/
,/t/
, or/b/
, depending on the type of component (sublibrary, executable, foreign library, test suite, or benchmark respectively). So the full path to an executable namedpexe
compiled with GHC 8.0.1 on a 64-bit Linux is nowdist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/x/pexe/build/pexe/pexe
; for a benchmark namedpbench
it now isdist-newstyle/build/x86_64-linux/ghc-8.0.1/p-0.1/b/pbench/build/pbench/pbench
;
- In cabal-install-2.2 and above, the
The paths are a bit longer in 2.0 and above but the benefit is that you can transparently have multiple builds with different versions of GHC. We plan to add the ability to create aliases for certain build configurations, and more convenient paths to access particularly useful build products like executables.
5.3.3. Caching¶
Nix-style local builds sport a robust caching system which help reduce
the time it takes to execute a rebuild cycle. While the details of how
cabal-install
does caching are an implementation detail and may
change in the future, knowing what gets cached is helpful for
understanding the performance characteristics of invocations to
v2-build
. The cached intermediate results are stored in
dist-newstyle/cache
; this folder can be safely deleted to clear the
cache.
The following intermediate results are cached in the following files in this folder (the most important two are first):
solver-plan
(binary)- The result of calling the dependency solver, assuming that the
Hackage index, local
cabal.project
file, and localcabal
files are unmodified. (Notably, we do NOT have to dependency solve again if new build products are stored in the global store; the invocation of the dependency solver is independent of what is already available in the store.) source-hashes
(binary)- The hashes of all local source files. When all local source files of
a local package are unchanged,
cabal v2-build
will skip invokingsetup build
entirely (saving us from a possibly expensive call toghc --make
). The full list of source files participating in compilation are determined usingsetup sdist --list-sources
(thus, if you do not list all your source files in a Cabal file, you may fail to recompile when you edit them.) config
(same format ascabal.project
)- The full project configuration, merged from
cabal.project
(and friends) as well as the command line arguments. compiler
(binary)- The configuration of the compiler being used to build the project.
improved-plan
(binary)- Like
solver-plan
, but with all non-inplace packages improved into pre-existing copies from the store. plan.json
(JSON)A JSON serialization of the computed install plan intended for integrating
cabal
with external tooling. The cabal-plan package provides a library for parsingplan.json
files into a Haskell data structure as well as an example tool showing possible applications.Todo
Document JSON schema (including version history of schema)
Note that every package also has a local cache managed by the Cabal
build system, e.g., in $distdir/cache
.
There is another useful file in dist-newstyle/cache
,
plan.json
, which is a JSON serialization of the computed install
plan and is intended for integrating with external tooling.
5.4. Commands¶
We now give an in-depth description of all the commands, describing the arguments and flags they accept.
5.4.1. cabal v2-configure¶
cabal v2-configure
takes a set of arguments and writes a
cabal.project.local
file based on the flags passed to this command.
cabal v2-configure FLAGS; cabal new-build
is roughly equivalent to
cabal v2-build FLAGS
, except that with new-configure
the flags
are persisted to all subsequent calls to v2-build
.
cabal v2-configure
is intended to be a convenient way to write out
a cabal.project.local
for simple configurations; e.g.,
cabal v2-configure -w ghc-7.8
would ensure that all subsequent
builds with cabal v2-build
are performed with the compiler
ghc-7.8
. For more complex configuration, we recommend writing the
cabal.project.local
file directly (or placing it in
cabal.project
!)
cabal v2-configure
inherits options from Cabal
. semantics:
- Any flag accepted by
./Setup configure
. - Any flag accepted by
cabal configure
beyond./Setup configure
, namely--cabal-lib-version
,--constraint
,--preference
and--solver.
- Any flag accepted by
cabal install
beyond./Setup configure
. - Any flag accepted by
./Setup haddock
.
The options of all of these flags apply only to local packages in a
project; this behavior is different than that of cabal install
,
which applies flags to every package that would be built. The motivation
for this is to avoid an innocuous addition to the flags of a package
resulting in a rebuild of every package in the store (which might need
to happen if a flag actually applied to every transitive dependency). To
apply options to an external package, use a package
stanza in a
cabal.project
file.
5.4.2. cabal v2-update¶
cabal v2-update
updates the state of the package index. If the
project contains multiple remote package repositories it will update
the index of all of them (e.g. when using overlays).
Some examples:
$ cabal v2-update # update all remote repos
$ cabal v2-update head.hackage # update only head.hackage
5.4.3. cabal v2-build¶
cabal v2-build
takes a set of targets and builds them. It
automatically handles building and installing any dependencies of these
targets.
A target can take any of the following forms:
A package target:
package
, which specifies that all enabled components of a package to be built. By default, test suites and benchmarks are not enabled, unless they are explicitly requested (e.g., via--enable-tests
.)A component target:
[package:][ctype:]component
, which specifies a specific component (e.g., a library, executable, test suite or benchmark) to be built.All packages:
all
, which specifies all packages within the project.Components of a particular type:
package:ctypes
,all:ctypes
: which specifies all components of the given type. Where validctypes
are:libs
,libraries
,flibs
,foreign-libraries
,exes
,executables
,tests
,benches
,benchmarks
.
In component targets, package:
and ctype:
(valid component types
are lib
, flib
, exe
, test
and bench
) can be used to
disambiguate when multiple packages define the same component, or the
same component name is used in a package (e.g., a package foo
defines both an executable and library named foo
). We always prefer
interpreting a target as a package name rather than as a component name.
Some example targets:
$ cabal v2-build lib:foo-pkg # build the library named foo-pkg
$ cabal v2-build foo-pkg:foo-tests # build foo-tests in foo-pkg
(There is also syntax for specifying module and file targets, but it doesn’t currently do anything.)
Beyond a list of targets, cabal v2-build
accepts all the flags that
cabal v2-configure
takes. Most of these flags are only taken into
consideration when building local packages; however, some flags may
cause extra store packages to be built (for example,
--enable-profiling
will automatically make sure profiling libraries
for all transitive dependencies are built and installed.)
In addition cabal v2-build
accepts these flags:
--only-configure
: When given we will forgoe performing a full build and abort after running the configure phase of each target package.
5.4.4. cabal v2-repl¶
cabal v2-repl TARGET
loads all of the modules of the target into
GHCi as interpreted bytecode. In addition to cabal v2-build
’s flags,
it takes an additional --repl-options
flag.
To avoid ghci
specific flags from triggering unneeded global rebuilds these
flags are now stripped from the internal configuration. As a result
--ghc-options
will no longer (reliably) work to pass flags to ghci
(or
other repls). Instead, you should use the new --repl-options
flag to
specify these options to the invoked repl. (This flag also works on cabal
repl
and Setup repl
on sufficiently new versions of Cabal.)
Currently, it is not supported to pass multiple targets to v2-repl
(v2-repl
will just successively open a separate GHCi session for
each target.)
It also provides a way to experiment with libraries without needing to download them manually or to install them globally.
This command opens a REPL with the current default target loaded, and a version
of the vector
package matching that specification exposed.
$ cabal v2-repl --build-depends "vector >= 0.12 && < 0.13"
Both of these commands do the same thing as the above, but only exposes base
,
vector
, and the vector
package’s transitive dependencies even if the user
is in a project context.
$ cabal v2-repl --ignore-project --build-depends "vector >= 0.12 && < 0.13"
$ cabal v2-repl --project='' --build-depends "vector >= 0.12 && < 0.13"
This command would add vector
, but not (for example) primitive
, because
it only includes the packages specified on the command line (and base
, which
cannot be excluded for technical reasons).
$ cabal v2-repl --build-depends vector --no-transitive-deps
5.4.5. cabal v2-run¶
cabal v2-run [TARGET [ARGS]]
runs the executable specified by the
target, which can be a component, a package or can be left blank, as
long as it can uniquely identify an executable within the project.
Tests and benchmarks are also treated as executables.
See the v2-build section for the target syntax.
Except in the case of the empty target, the strings after it will be passed to the executable as arguments.
If one of the arguments starts with -
it will be interpreted as
a cabal flag, so if you need to pass flags to the executable you
have to separate them with --
.
$ cabal v2-run target -- -a -bcd --argument
‘v2-run’ also supports running script files that use a certain format. With a script that looks like:
#!/usr/bin/env cabal
{- cabal:
build-depends: base ^>= 4.11
, shelly ^>= 1.8.1
-}
main :: IO ()
main = do
...
It can either be executed like any other script, using cabal
as an
interpreter, or through this command:
$ cabal v2-run script.hs
$ cabal v2-run script.hs -- --arg1 # args are passed like this
5.4.6. cabal v2-freeze¶
cabal v2-freeze
writes out a freeze file which records all of
the versions and flags which that are picked by the solver under the
current index and flags. Default name of this file is
cabal.project.freeze
but in combination with a
--project-file=my.project
flag (see project-file)
the name will be my.project.freeze
.
A freeze file has the same syntax as cabal.project
and looks
something like this:
constraints: HTTP ==4000.3.3,
HTTP +warp-tests -warn-as-error -network23 +network-uri -mtl1 -conduit10,
QuickCheck ==2.9.1,
QuickCheck +templatehaskell,
-- etc...
For end-user executables, it is recommended that you distribute the
cabal.project.freeze
file in your source repository so that all
users see a consistent set of dependencies. For libraries, this is not
recommended: users often need to build against different versions of
libraries than what you developed against.
5.4.7. cabal v2-bench¶
cabal v2-bench [TARGETS] [OPTIONS]
runs the specified benchmarks
(all the benchmarks in the current package by default), first ensuring
they are up to date.
5.4.8. cabal v2-test¶
cabal v2-test [TARGETS] [OPTIONS]
runs the specified test suites
(all the test suites in the current package by default), first ensuring
they are up to date.
5.4.9. cabal v2-haddock¶
cabal v2-haddock [FLAGS] [TARGET]
builds Haddock documentation for
the specified packages within the project.
If a target is not a library haddock-benchmarks
,
haddock-executables
, haddock-internal
,
haddock-tests
will be implied as necessary.
5.4.10. cabal v2-exec¶
cabal v2-exec [FLAGS] [--] COMMAND [--] [ARGS]
runs the specified command
using the project’s environment. That is, passing the right flags to compiler
invocations and bringing the project’s executables into scope.
5.4.11. cabal v2-install¶
cabal v2-install [FLAGS] PACKAGES
builds the specified packages and
symlinks/copies their executables in installdir
(usually ~/.cabal/bin
).
For example this command will build the latest cabal-install
and symlink
its cabal
executable:
$ cabal v2-install cabal-install
In addition, it’s possible to use cabal v2-install
to install components
of a local project. For example, with an up-to-date Git clone of the Cabal
repository, this command will build cabal-install HEAD and symlink the
cabal
executable:
$ cabal v2-install exe:cabal
Where symlinking is not possible (eg. on Windows), --install-method=copy
can be used:
$ cabal v2-install exe:cabal --install-method=copy --installdir=~/bin
Note that copied executables are not self-contained, since they might use data-files from the store.
It is also possible to “install” libraries using the --lib
flag. For
example, this command will build the latest Cabal library and install it:
$ cabal v2-install --lib Cabal
This works by managing GHC environments. By default, it is writing to the
global environment in ~/.ghc/$ARCH-$OS-$GHCVER/environments/default
.
v2-install
provides the --package-env
flag to control which of
these environments is modified.
This command will modify the environment file in the current directory:
$ cabal v2-install --lib Cabal --package-env .
This command will modify the environment file in the ~/foo
directory:
$ cabal v2-install --lib Cabal --package-env foo/
Do note that the results of the previous two commands will be overwritten by the use of other v2-style commands, so it is not recommended to use them inside a project directory.
This command will modify the environment in the “local.env” file in the current directory:
$ cabal v2-install --lib Cabal --package-env local.env
This command will modify the myenv
named global environment:
$ cabal v2-install --lib Cabal --package-env myenv
If you wish to create a named environment file in the current directory where
the name does not contain an extension, you must reference it as ./myenv
.
You can learn more about how to use these environments in this section of the GHC manual.
5.4.12. cabal v2-clean¶
cabal v2-clean [FLAGS]
cleans up the temporary files and build artifacts
stored in the dist-newstyle
folder.
By default, it removes the entire folder, but it can also spare the configuration
and caches if the --save-config
option is given, in which case it only removes
the build artefacts (.hi
, .o
along with any other temporary files generated
by the compiler, along with the build output).
5.4.13. cabal v2-sdist¶
cabal v2-sdist [FLAGS] [TARGETS]
takes the crucial files needed to build TARGETS
and puts them into an archive format ready for upload to Hackage. These archives are stable
and two archives of the same format built from the same source will hash to the same value.
cabal v2-sdist
takes the following flags:
-l
,--list-only
: Rather than creating an archive, lists files that would be included. Output is tostdout
by default. The file paths are relative to the project’s root directory.-o
,--output-dir
: Sets the output dir, if a non-default one is desired. The default isdist-newstyle/sdist/
.--output-dir -
will send output tostdout
unless multiple archives are being created.-z
,--null
: Only used with--list-only
. Separates filenames with a NUL byte instead of newlines.
v2-sdist
is inherently incompatible with sdist hooks, not due to implementation but due
to fundamental core invariants (same source code should result in the same tarball, byte for
byte) that must be satisfied for it to function correctly in the larger v2-build ecosystem.
autogen-modules
is able to replace uses of the hooks to add generated modules, along with
the custom publishing of Haddock documentation to Hackage.
5.5. Configuring builds with cabal.project¶
cabal.project
files support a variety of options which configure the
details of your build. The general syntax of a cabal.project
file is
similar to that of a Cabal file: there are a number of fields, some of
which live inside stanzas:
packages: */*.cabal
with-compiler: /opt/ghc/8.0.1/bin/ghc
package cryptohash
optimization: False
In general, the accepted field names coincide with the accepted command
line flags that cabal install
and other commands take. For example,
cabal v2-configure --enable-profiling
will write out a project
file with profiling: True
.
The full configuration of a project is determined by combining the following sources (later entries override earlier ones):
~/.cabal/config
(the user-wide global configuration)cabal.project
(the project configuration)cabal.project.freeze
(the output ofcabal v2-freeze
)cabal.project.local
(the output ofcabal v2-configure
)
5.5.1. Specifying the local packages¶
The following top-level options specify what the local packages of a project are:
-
packages
:
package location list (space or comma separated)¶ Default value: ./*.cabal
Specifies the list of package locations which contain the local packages to be built by this project. Package locations can take the following forms:
- They can specify a Cabal file, or a directory containing a Cabal
file, e.g.,
packages: Cabal cabal-install/cabal-install.cabal
. - They can specify a glob-style wildcards, which must match one or
more (a) directories containing a (single) Cabal file, (b) Cabal
files (extension
.cabal
), or (c) tarballs which contain Cabal packages (extension.tar.gz
). For example, to match all Cabal files in all subdirectories, as well as the Cabal projects in the parent directoriesfoo
andbar
, usepackages: */*.cabal ../{foo,bar}/
- They can specify an
http
,https
orfile
URL, representing the path to a remote tarball to be downloaded and built.
There is no command line variant of this field; see #3585.
- They can specify a Cabal file, or a directory containing a Cabal
file, e.g.,
-
optional-packages
:
package location list (space or comma-separated)¶ Default value: ./*/*.cabal
Like
packages
, specifies a list of package locations containing local packages to be built. Unlikepackages
, if we glob for a package, it is permissible for the glob to match against zero packages. The intended use-case foroptional-packages
is to make it so that vendored packages can be automatically picked up if they are placed in a subdirectory, but not error if there aren’t any.There is no command line variant of this field.
-
extra-packages
:
package list with version bounds (comma separated)¶ [STRIKEOUT:Specifies a list of external packages from Hackage which should be considered local packages.] (Not implemented)
There is no command line variant of this field.
All local packages are vendored, in the sense that if other packages (including external ones from Hackage) depend on a package with the name of a local package, the local package is preferentially used. This motivates the default settings:
packages: ./*.cabal
optional-packages: ./*/*.cabal
…any package can be vendored simply by making a checkout in the top-level project directory, as might be seen in this hypothetical directory layout:
foo.cabal
foo-helper/ # local package
unix/ # vendored external package
All of these options support globs. cabal v2-build
has its own glob
format:
- Anywhere in a path, as many times as you like, you can specify an
asterisk
*
wildcard. E.g.,*/*.cabal
matches all.cabal
files in all immediate subdirectories. Like in glob(7), asterisks do not match hidden files unless there is an explicit period, e.g.,.*/foo.cabal
will match.private/foo.cabal
(but*/foo.cabal
will not). - You can use braces to specify specific directories; e.g.,
{vendor,pkgs}/*.cabal
matches all Cabal files in thevendor
andpkgs
subdirectories.
Formally, the format described by the following BNF:
Todo
convert globbing grammar to proper ABNF syntax
FilePathGlob ::= FilePathRoot FilePathGlobRel
FilePathRoot ::= {- empty -} # relative to cabal.project
| "/" # Unix root
| [a-zA-Z] ":" [/\\] # Windows root
| "~" # home directory
FilePathGlobRel ::= Glob "/" FilePathGlobRel # Unix directory
| Glob "\\" FilePathGlobRel # Windows directory
| Glob # file
| {- empty -} # trailing slash
Glob ::= GlobPiece *
GlobPiece ::= "*" # wildcard
| [^*{},/\\] * # literal string
| "\\" [*{},] # escaped reserved character
| "{" Glob "," ... "," Glob "}" # union (match any of these)
<IP_ADDRESS>. Specifying Packages from Remote Version Control Locations¶
Starting with Cabal 2.4, there is now a stanza
source-repository-package
for specifying packages from an external
version control which supports the following fields:
A simple example is shown below:
packages: .
source-repository-package
type: git
location: https://github.com/hvr/HsYAML.git
tag: e70cf0c171c9a586b62b3f75d72f1591e4e6aaa1
source-repository-package
type: git
location: https://github.com/well-typed/cborg
tag: 3d274c14ca3077c3a081ba7ad57c5182da65c8c1
subdir: cborg
5.5.2. Global configuration options¶
The following top-level configuration options are not specific to any package, and thus apply globally:
-
verbose
:
nat¶ -
--verbose
=n
,
-vn
¶ Default value: 1 Control the verbosity of
cabal
commands, valid values are from 0 to 3.The command line variant of this field is
--verbose=2
; a short form-v2
is also supported.
-
jobs
:
nat or $ncpus¶ -
--jobs
=n
,
-jn
,
--jobs
=$ncpus
¶ Default value: 1 Run nat jobs simultaneously when building. If
$ncpus
is specified, run the number of jobs equal to the number of CPUs. Package building is often quite parallel, so turning on parallelism can speed up build times quite a bit!The command line variant of this field is
--jobs=2
; a short form-j2
is also supported; a bare--jobs
or-j
is equivalent to--jobs=$ncpus
.
-
keep-going
:
boolean¶ -
--keep-going
¶ Default value: False If true, after a build failure, continue to build other unaffected packages.
The command line variant of this field is
--keep-going
.
-
--builddir
=DIR
¶ Specifies the name of the directory where build products for build will be stored; defaults to
dist-newstyle
. If a relative name is specified, this directory is resolved relative to the root of the project (i.e., where thecabal.project
file lives.)This option cannot be specified via a
cabal.project
file.
-
--project-file
=FILE
¶ Specifies the name of the project file used to specify the rest of the top-level configuration; defaults to
cabal.project
. This name not only specifies the name of the main project file, but also the auxiliary project filescabal.project.freeze
andcabal.project.local
; for example, if you specify--project-file=my.project
, then the other files that will be probed aremy.project.freeze
andmy.project.local
.If the specified project file is a relative path, we will look for the file relative to the current working directory, and then for the parent directory, until the project file is found or we have hit the top of the user’s home directory.
This option cannot be specified via a
cabal.project
file.
-
--store-dir
=DIR
¶ Specifies the name of the directory of the global package store.
5.5.3. Solver configuration options¶
The following settings control the behavior of the dependency solver:
-
constraints
:
constraints list (comma separated)¶ -
--constraint
="pkg > 2.0"
¶ Add extra constraints to the version bounds, flag settings, and other properties a solver can pick for a package. For example:
constraints: bar == 2.1
A package can be specified multiple times in
constraints
, in which case the specified constraints are intersected. This is useful, since the syntax does not allow you to specify multiple constraints at once. For example, to specify both version bounds and flag assignments, you would write:constraints: bar == 2.1, bar +foo -baz
Valid constraints take the same form as for the constraint command line option.
-
preferences
:
preference (comma separated)¶ -
--preference
="pkg > 2.0"
¶ Like
constraints
, but the solver will attempt to satisfy these preferences on a best-effort basis. The resulting install is locally optimal with respect to preferences; specifically, no single package could be replaced with a more preferred version that still satisfies the hard constraints.Operationally, preferences can cause the solver to attempt certain version choices of a package before others, which can improve dependency solver runtime.
One way to use
preferences
is to take a known working set of constraints (e.g., viacabal v2-freeze
) and record them as preferences. In this case, the solver will first attempt to use this configuration, and if this violates hard constraints, it will try to find the minimal number of upgrades to satisfy the hard constraints again.The command line variant of this field is
--preference="pkg >= 2.0"
; to specify multiple preferences, pass the flag multiple times.
-
allow-newer
:
none, all or list of scoped package names (space or comma separated)¶ -
--allow-newer
,
--allow-newer
=[none
,
all
,
[scope:][^]pkg]
¶ Default value: none
Allow the solver to pick an newer version of some packages than would normally be permitted by than the
build-depends
bounds of packages in the install plan. This option may be useful if the dependency solver cannot otherwise find a valid install plan.For example, to relax
pkg
sbuild-depends
upper bound ondep-pkg
, write a scoped package name of the form:allow-newer: pkg:dep-pkg
If the scope shall be limited to specific releases of
pkg
, the extended form as inallow-newer: pkg-1.2.3:dep-pkg, pkg-1.1.2:dep-pkg
can be used to limit the relaxation of dependencies on
dep-pkg
by thepkg-1.2.3
andpkg-1.1.2
releases only.The scoped syntax is recommended, as it is often only a single package whose upper bound is misbehaving. In this case, the upper bounds of other packages should still be respected; indeed, relaxing the bound can break some packages which test the selected version of packages.
The syntax also allows to prefix the dependee package with a modifier symbol to modify the scope/semantic of the relaxation transformation in a additional ways. Currently only one modifier symbol is defined, i.e.
^
(i.e. caret) which causes the relaxation to be applied only to^>=
operators and leave all other version operators untouched.However, in some situations (e.g., when attempting to build packages on a new version of GHC), it is useful to disregard all upper-bounds, with respect to a package or all packages. This can be done by specifying just a package name, or using the keyword
all
to specify all packages:-- Disregard upper bounds involving the dependencies on -- packages bar, baz. For quux only, relax -- 'quux ^>= ...'-style constraints only. allow-newer: bar, baz, ^quux -- Disregard all upper bounds when dependency solving allow-newer: all -- Disregard all `^>=`-style upper bounds when dependency solving allow-newer: ^all
For consistency, there is also the explicit wildcard scope syntax
*
(or its alphabetic synonymall
). Consequently, the examples above are equivalent to the explicitly scoped variants:allow-newer: all:bar, *:baz, *:^quux allow-newer: *:* allow-newer: all:all allow-newer: *:^* allow-newer: all:^all
In order to ignore all bounds specified by a package
pkg-1.2.3
you can combine scoping with a right-hand-side wildcard like so-- Disregard any upper bounds specified by pkg-1.2.3 allow-newer: pkg-1.2.3:* -- Disregard only `^>=`-style upper bounds in pkg-1.2.3 allow-newer: pkg-1.2.3:^*
allow-newer
is often used in conjunction with a constraint (in the cfg-field:constraints field) forcing the usage of a specific, newer version of a package.The command line variant of this field is e.g.
--allow-newer=bar
. A bare--allow-newer
is equivalent to--allow-newer=all
.
-
allow-older
:
none, all, list of scoped package names (space or comma separated)¶ -
--allow-older
,
--allow-older
=[none
,
all
,
[scope:][^]pkg]
¶ Since: Cabal 2.0 Default value: none
Like
allow-newer
, but applied to lower bounds rather than upper bounds.The command line variant of this field is
--allow-older=all
. A bare--allow-older
is equivalent to--allow-older=all
.
-
index-state
:
HEAD, unix-timestamp, ISO8601 UTC timestamp.¶ Since: Cabal 2.0 Default value: HEAD
This allows to change the source package index state the solver uses to compute install-plans. This is particularly useful in combination with freeze-files in order to also freeze the state the package index was in at the time the install-plan was frozen.
-- UNIX timestamp format example index-state: @1474739268 -- ISO8601 UTC timestamp format example -- This format is used by 'cabal v2-configure' -- for storing `--index-state` values. index-state: 2016-09-24T17:47:48Z
-
reject-unconstrained-dependencies
:
all, none¶ -
--reject-unconstrained-dependencies
=[all|none]
¶ Default value: none Since: 2.6 By default, the dependency solver can include any package that it’s aware of in a build plan. If you wish to restrict the build plan to a closed set of packages (e.g., from a freeze file), use this flag.
When set to all, all non-local packages that aren’t goals must be explicitly constrained. When set to none, the solver will consider all packages.
5.5.4. Package configuration options¶
Package options affect the building of specific packages. There are three ways a package option can be specified:
- They can be specified at the top-level, in which case they apply only to local package, or
- They can be specified inside a
package
stanza, in which case they apply to the build of the package, whether or not it is local or external. - They can be specified inside an
package *
stanza, in which case they apply to all packages, local ones from the project and also external dependencies.
For example, the following options specify that optimization
should be turned off for all local packages, and that bytestring
(possibly
an external dependency) should be built with -fno-state-hack
:
optimization: False
package bytestring
ghc-options: -fno-state-hack
ghc-options
is not specifically described in this documentation,
but is one of many fields for configuring programs. They take the form
progname-options
and progname-location
, and
can only be set inside package stanzas. (TODO: They are not supported
at top-level, see #3579.)
At the moment, there is no way to specify an option to apply to all external packages or all inplace packages. Additionally, it is only possible to specify these options on the command line for all local packages (there is no per-package command line interface.)
Some flags were added by more recent versions of the Cabal library. This means that they are NOT supported by packages which use Custom setup scripts that require a version of the Cabal library older than when the feature was added.
-
flags
:
list of +flagname or -flagname (space separated)¶ -
--flags
="+foo -bar"
,
-ffoo
,
-f-bar
¶ Force all flags specified as
+flagname
to be true, and all flags specified as-flagname
to be false. For example, to enable the flagfoo
and disablebar
, set:flags: +foo -bar
If there is no leading punctuation, it is assumed that the flag should be enabled; e.g., this is equivalent:
flags: foo -bar
Flags are per-package, so it doesn’t make much sense to specify flags at the top-level, unless you happen to know that all of your local packages support the same named flags. If a flag is not supported by a package, it is ignored.
See also the solver configuration field
constraints
.The command line variant of this flag is
--flags
. There is also a shortened form-ffoo -f-bar
.A common mistake is to say
cabal v2-build -fhans
, wherehans
is a flag for a transitive dependency that is not in the local package; in this case, the flag will be silently ignored. Ifhaskell-tor
is the package you want this flag to apply to, try--constraint="haskell-tor +hans"
instead.
-
with-compiler
:
executable¶ -
--with-compiler
=executable
¶ Specify the path to a particular compiler to be used. If not an absolute path, it will be resolved according to the
PATH
environment. The type of the compiler (GHC, GHCJS, etc) must be consistent with the setting of thecompiler
field.The most common use of this option is to specify a different version of your compiler to be used; e.g., if you have
ghc-7.8
in your path, you can specifywith-compiler: ghc-7.8
to use it.This flag also sets the default value of
with-hc-pkg
, using the heuristic that it is namedghc-pkg-7.8
(if your executable name is suffixed with a version number), or is the executable namedghc-pkg
in the same directory as theghc
directory. If this heuristic does not work, setwith-hc-pkg
explicitly.For inplace packages,
cabal v2-build
maintains a separate build directory for each version of GHC, so you can maintain multiple build trees for different versions of GHC without clobbering each other.At the moment, it’s not possible to set
with-compiler
on a per-package basis, but eventually we plan on relaxing this restriction. If this is something you need, give us a shout.The command line variant of this flag is
--with-compiler=ghc-7.8
; there is also a short version-w ghc-7.8
.
-
with-hc-pkg
:
executable¶ -
--with-hc-pkg
=executable
¶ Specify the path to the package tool, e.g.,
ghc-pkg
. This package tool must be compatible with the compiler specified bywith-compiler
(generally speaking, it should be precisely the tool that was distributed with the compiler). If this option is omitted, the default value is determined fromwith-compiler
.The command line variant of this flag is
--with-hc-pkg=ghc-pkg-7.8
.
-
optimization
:
nat¶ -
--enable-optimization
¶ -
--disable-optimization
¶ Default value: 1
Build with optimization. This is appropriate for production use, taking more time to build faster libraries and programs.
The optional nat value is the optimisation level. Some compilers support multiple optimisation levels. The range is 0 to 2. Level 0 disables optimization, level 1 is the default. Level 2 is higher optimisation if the compiler supports it. Level 2 is likely to lead to longer compile times and bigger generated code. If you are not planning to run code, turning off optimization will lead to better build times and less code to be rebuilt when a module changes.
When optimizations are enabled, Cabal passes
-O2
to the C compiler.We also accept
True
(equivalent to 1) andFalse
(equivalent to 0).Note that as of GHC 8.0, GHC does not recompile when optimization levels change (see GHC #10923), so if you change the optimization level for a local package you may need to blow away your old build products in order to rebuild with the new optimization level.
The command line variant of this flag is
-O2
(with-O1
equivalent to-O
). There are also long-form variants--enable-optimization
and--disable-optimization
.
-
configure-options
:
args (space separated)¶ -
--configure-option
=arg
¶ A list of extra arguments to pass to the external
./configure
script, if one is used. This is only useful for packages which have theConfigure
build type. See also the section on system-dependent parameters.The command line variant of this flag is
--configure-option=arg
, which can be specified multiple times to pass multiple options.
-
compiler
:
ghc, ghcjs, jhc, lhc, uhc or haskell-suite¶ -
--compiler
=compiler
¶ Default value: ghc
Specify which compiler toolchain to be used. This is independent of
with-compiler
, because the choice of toolchain affects Cabal’s build logic.The command line variant of this flag is
--compiler=ghc
.
-
tests
:
boolean¶ -
--enable-tests
¶ -
--disable-tests
¶ Default value: False
Force test suites to be enabled. For most users this should not be needed, as we always attempt to solve for test suite dependencies, even when this value is
False
; furthermore, test suites are automatically enabled if they are requested as a built target.The command line variant of this flag is
--enable-tests
and--disable-tests
.
-
benchmarks
:
boolean¶ -
--enable-benchmarks
¶ -
--disable-benchmarks
¶ Default value: False
Force benchmarks to be enabled. For most users this should not be needed, as we always attempt to solve for benchmark dependencies, even when this value is
False
; furthermore, benchmarks are automatically enabled if they are requested as a built target.The command line variant of this flag is
--enable-benchmarks
and--disable-benchmarks
.
-
extra-prog-path
:
paths (newline or comma separated)¶ -
--extra-prog-path
=PATH
¶ Since: Cabal 1.18 A list of directories to search for extra required programs. Most users should not need this, as programs like
happy
andalex
will automatically be installed and added to the path. This can be useful if aCustom
setup script relies on an exotic extra program.The command line variant of this flag is
--extra-prog-path=PATH
, which can be specified multiple times.
-
run-tests
:
boolean¶ -
--run-tests
¶ Default value: False
Run the package test suite upon installation. This is useful for saying “When this package is installed, check that the test suite passes, terminating the rest of the build if it is broken.”
Warning
One deficiency: the
run-tests
setting of a package is NOT recorded as part of the hash, so if you install something withoutrun-tests
and then turn onrun-tests
, we won’t subsequently test the package. If this is causing you problems, give us a shout.The command line variant of this flag is
--run-tests
.
-
debug-info
:
integer¶ -
--enable-debug-info
=⟨n⟩
¶ -
--disable-debug-info
¶ Since: Cabal 1.22 Default value: False If the compiler (e.g., GHC 7.10 and later) supports outputing OS native debug info (e.g., DWARF), setting
debug-info: True
will instruct it to do so. See the GHC wiki page on DWARF for more information about this feature.(This field also accepts numeric syntax, but until GHC 8.2 this didn’t do anything.)
The command line variant of this flag is
--enable-debug-info
and--disable-debug-info
.
-
split-sections
:
boolean¶ -
--enable-split-sections
¶ -
--disable-split-sections
¶ Since: Cabal 2.2 Default value: False Use the GHC
-split-sections
feature when building the library. This reduces the final size of the executables that use the library by allowing them to link with only the bits that they use rather than the entire library. The downside is that building the library takes longer and uses a bit more memory.This feature is supported by GHC 8.0 and later.
The command line variant of this flag is
--enable-split-sections
and--disable-split-sections
.
-
split-objs
:
boolean¶ -
--enable-split-objs
¶ -
--disable-split-objs
¶ Default value: False Use the GHC
-split-objs
feature when building the library. This reduces the final size of the executables that use the library by allowing them to link with only the bits that they use rather than the entire library. The downside is that building the library takes longer and uses considerably more memory.It is generally recommend that you use
split-sections
instead ofsplit-objs
where possible.The command line variant of this flag is
--enable-split-objs
and--disable-split-objs
.
-
executable-stripping
:
boolean¶ -
--enable-executable-stripping
¶ -
--disable-executable-stripping
¶ Default value: True When installing binary executable programs, run the
strip
program on the binary. This can considerably reduce the size of the executable binary file. It does this by removing debugging information and symbols.Not all Haskell implementations generate native binaries. For such implementations this option has no effect.
If
debug-info
is set explicitly thenexecutable-stripping
is set toFalse
as otherwise all the debug symbols will be stripped.The command line variant of this flag is
--enable-executable-stripping
and--disable-executable-stripping
.
-
library-stripping
:
boolean¶ -
--enable-library-stripping
¶ -
--disable-library-stripping
¶ Since: Cabal 1.20 When installing binary libraries, run the
strip
program on the binary, saving space on the file system. See alsoexecutable-stripping
.If
debug-info
is set explicitly thenlibrary-stripping
is set toFalse
as otherwise all the debug symbols will be stripped.The command line variant of this flag is
--enable-library-stripping
and--disable-library-stripping
.
-
program-prefix
:
prefix¶ -
--program-prefix
=prefix
¶ [STRIKEOUT:Prepend prefix to installed program names.] (Currently implemented in a silly and not useful way. If you need this to work give us a shout.)
prefix may contain the following path variables:
$pkgid
,$pkg
,$version
,$compiler
,$os
,$arch
,$abi
,$abitag
The command line variant of this flag is
--program-prefix=foo-
.
-
program-suffix
:
suffix¶ -
--program-suffix
=suffix
¶ [STRIKEOUT:Append suffix to installed program names.] (Currently implemented in a silly and not useful way. If you need this to work give us a shout.)
The most obvious use for this is to append the program’s version number to make it possible to install several versions of a program at once:
program-suffix: $version
.suffix may contain the following path variables:
$pkgid
,$pkg
,$version
,$compiler
,$os
,$arch
,$abi
,$abitag
The command line variant of this flag is
--program-suffix='$version'
.
Default value: False Build shared library. This implies a separate compiler run to generate position independent code as required on most platforms.
The command line variant of this flag is
--enable-shared
and--disable-shared
.
-
executable-dynamic
:
boolean¶ -
--enable-executable-dynamic
¶ -
--disable-executable-dynamic
¶ Default value: False Link executables dynamically. The executable’s library dependencies should be built as shared objects. This implies
shared: True
unlessshared: False
is explicitly specified.The command line variant of this flag is
--enable-executable-dynamic
and--disable-executable-dynamic
.
-
library-for-ghci
:
boolean¶ -
--enable-library-for-ghci
¶ -
--disable-library-for-ghci
¶ Default value: True Build libraries suitable for use with GHCi. This involves an extra linking step after the build.
Not all platforms support GHCi and indeed on some platforms, trying to build GHCi libs fails. In such cases, consider setting
library-for-ghci: False
.The command line variant of this flag is
--enable-library-for-ghci
and--disable-library-for-ghci
.
-
relocatable
:
¶ -
--relocatable
¶ Since: Cabal 1.22 Default value: False [STRIKEOUT:Build a package which is relocatable.] (TODO: It is not clear what this actually does, or if it works at all.)
The command line variant of this flag is
--relocatable
.
-
static
:
boolean¶ -
--enable-static
¶ -
--disable-static
¶ Default value: False Roll this and all dependent libraries into a combined
.a
archive. This uses GHCs-staticlib
flag, which is available for iOS and with GHC 8.4 and later for other platforms as well.
-
executable-static
:
boolean¶ -
--enable-executable-static
¶ -
--disable-executable-static
¶ Default value: False Build fully static executables. This link all dependent libraries into executables statically, including libc. This passes
-static
and-optl=-static
to GHC.
-
extra-include-dirs
:
directories (comma or newline separated list)¶ -
--extra-include-dirs
=DIR
¶ An extra directory to search for C header files. You can use this flag multiple times to get a list of directories.
You might need to use this flag if you have standard system header files in a non-standard location that is not mentioned in the package’s
.cabal
file. Using this option has the same affect as appending the directory dir to theinclude-dirs
field in each library and executable in the package’s.cabal
file. The advantage of course is that you do not have to modify the package at all. These extra directories will be used while building the package and for libraries it is also saved in the package registration information and used when compiling modules that use the library.The command line variant of this flag is
--extra-include-dirs=DIR
, which can be specified multiple times.
-
extra-lib-dirs
:
directories (comma or newline separated list)¶ -
--extra-lib-dirs
=DIR
¶ An extra directory to search for system libraries files.
The command line variant of this flag is
--extra-lib-dirs=DIR
, which can be specified multiple times.
-
extra-framework-dirs
:
directories (comma or newline separated list)¶ -
--extra-framework-dirs
=DIR
¶ An extra directory to search for frameworks (OS X only).
You might need to use this flag if you have standard system libraries in a non-standard location that is not mentioned in the package’s
.cabal
file. Using this option has the same affect as appending the directory dir to theextra-lib-dirs
field in each library and executable in the package’s.cabal
file. The advantage of course is that you do not have to modify the package at all. These extra directories will be used while building the package and for libraries it is also saved in the package registration information and used when compiling modules that use the library.The command line variant of this flag is
--extra-framework-dirs=DIR
, which can be specified multiple times.
-
profiling
:
boolean¶ -
--enable-profiling
¶ -
--disable-profiling
¶ Since: Cabal 1.22 Default value: False Build libraries and executables with profiling enabled (for compilers that support profiling as a separate mode). It is only necessary to specify
profiling
for the specific package you want to profile;cabal v2-build
will ensure that all of its transitive dependencies are built with profiling enabled.To enable profiling for only libraries or executables, see
library-profiling
andexecutable-profiling
.For useful profiling, it can be important to control precisely what cost centers are allocated; see
profiling-detail
.The command line variant of this flag is
--enable-profiling
and--disable-profiling
.
-
profiling-detail
:
level¶ -
--profiling-detail
=level
¶ Since: Cabal 1.24 Some compilers that support profiling, notably GHC, can allocate costs to different parts of the program and there are different levels of granularity or detail with which this can be done. In particular for GHC this concept is called “cost centers”, and GHC can automatically add cost centers, and can do so in different ways.
This flag covers both libraries and executables, but can be overridden by the
library-profiling-detail
field.Currently this setting is ignored for compilers other than GHC. The levels that cabal currently supports are:
- default
- For GHC this uses
exported-functions
for libraries andtoplevel-functions
for executables. - none
- No costs will be assigned to any code within this component.
- exported-functions
- Costs will be assigned at the granularity of all top level
functions exported from each module. In GHC, this
is for non-inline functions. Corresponds to
-fprof-auto-exported
. - toplevel-functions
- Costs will be assigned at the granularity of all top level
functions in each module, whether they are exported from the
module or not. In GHC specifically, this is for non-inline
functions. Corresponds to
-fprof-auto-top
. - all-functions
- Costs will be assigned at the granularity of all functions in
each module, whether top level or local. In GHC specifically,
this is for non-inline toplevel or where-bound functions or
values. Corresponds to
-fprof-auto
.
The command line variant of this flag is
--profiling-detail=none
.
-
library-profiling-detail
:
level¶ -
--library-profiling-detail
=level
¶ Since: Cabal 1.24 Like
profiling-detail
, but applied only to librariesThe command line variant of this flag is
--library-profiling-detail=none
.
-
library-vanilla
:
boolean¶ -
--enable-library-vanilla
¶ -
--disable-library-vanilla
¶ Default value: True Build ordinary libraries (as opposed to profiling libraries). Mostly, you can set this to False to avoid building ordinary libraries when you are profiling.
The command line variant of this flag is
--enable-library-vanilla
and--disable-library-vanilla
.
-
library-profiling
:
boolean¶ -
--enable-library-profiling
¶ -
--disable-library-profiling
¶ Since: Cabal 1.22 Default value: False Build libraries with profiling enabled. You probably want to use
profiling
instead.The command line variant of this flag is
--enable-library-profiling
and--disable-library-profiling
.
-
executable-profiling
:
boolean¶ -
--enable-executable-profiling
¶ -
--disable-executable-profiling
¶ Since: Cabal 1.22 Default value: False Build executables with profiling enabled. You probably want to use
profiling
instead.The command line variant of this flag is
--enable-executable-profiling
and--disable-executable-profiling
.
-
coverage
:
boolean¶ -
--enable-coverage
¶ -
--disable-coverage
¶ Since: Cabal 1.22 Default value: False Build libraries and executables (including test suites) with Haskell Program Coverage enabled. Running the test suites will automatically generate coverage reports with HPC.
The command line variant of this flag is
--enable-coverage
and--disable-coverage
.
-
library-coverage
:
boolean¶ -
--enable-library-coverage
¶ -
--disable-library-coverage
¶ Deprecated: Since: Cabal 1.22 Default value: False Deprecated, use
coverage
.The command line variant of this flag is
--enable-library-coverage
and--disable-library-coverage
.
-
documentation
:
boolean¶ -
--enable-documentation
¶ -
--disable-documentation
¶ Default value: False Enables building of Haddock documentation
The command line variant of this flag is
--enable-documentation
and--disable-documentation
.documentation: true does not imply
haddock-benchmarks
,haddock-executables
,haddock-internal
orhaddock-tests
. These need to be enabled separately if desired.
-
doc-index-file
:
templated path¶ -
--doc-index-file
=TEMPLATE
¶ A central index of Haddock API documentation (template cannot use
$pkgid
), which should be updated as documentation is built.The command line variant of this flag is
--doc-index-file=TEMPLATE
The following commands are equivalent to ones that would be passed when
running setup haddock
. (TODO: Where does the documentation get put.)
-
haddock-hoogle
:
boolean¶ Default value: False Generate a text file which can be converted by Hoogle into a database for searching. This is equivalent to running
haddock
with the--hoogle
flag.The command line variant of this flag is
--hoogle
(for thehaddock
command).
-
haddock-html
:
boolean¶ Default value: True Build HTML documentation.
The command line variant of this flag is
--html
(for thehaddock
command).
-
haddock-html-location
:
templated path¶ Specify a template for the location of HTML documentation for prerequisite packages. The substitutions are applied to the template to obtain a location for each package, which will be used by hyperlinks in the generated documentation. For example, the following command generates links pointing at [Hackage] pages:
html-location: 'http://hackage.haskell.org/packages/archive/$pkg/latest/doc/html'
Here the argument is quoted to prevent substitution by the shell. If this option is omitted, the location for each package is obtained using the package tool (e.g.
ghc-pkg
).The command line variant of this flag is
--html-location
(for thehaddock
subcommand).
-
haddock-executables
:
boolean¶ Default value: False Run haddock on all executable programs.
The command line variant of this flag is
--executables
(for thehaddock
subcommand).
-
haddock-tests
:
boolean¶ Default value: False Run haddock on all test suites.
The command line variant of this flag is
--tests
(for thehaddock
subcommand).
-
haddock-benchmarks
:
boolean¶ Default value: False Run haddock on all benchmarks.
The command line variant of this flag is
--benchmarks
(for thehaddock
subcommand).
-
haddock-all
:
boolean¶ Default value: False Run haddock on all components.
The command line variant of this flag is
--all
(for thehaddock
subcommand).
-
haddock-internal
:
boolean¶ Default value: False Build haddock documentation which includes unexposed modules and symbols.
The command line variant of this flag is
--internal
(for thehaddock
subcommand).
-
haddock-css
:
path¶ The CSS file that should be used to style the generated documentation (overriding haddock’s default.)
The command line variant of this flag is
--css
(for thehaddock
subcommand).
-
haddock-hyperlink-source
:
boolean¶ Default value: False Generated hyperlinked source code using HsColour, and have Haddock documentation link to it.
The command line variant of this flag is
--hyperlink-source
(for thehaddock
subcommand).
-
haddock-hscolour-css
:
path¶ The CSS file that should be used to style the generated hyperlinked source code (from HsColour).
The command line variant of this flag is
--hscolour-css
(for thehaddock
subcommand).
-
haddock-contents-location
:
URL¶ A baked-in URL to be used as the location for the contents page.
The command line variant of this flag is
--contents-location
(for thehaddock
subcommand).
-
haddock-keep-temp-files
:
boolean¶ Keep temporary files.
The command line variant of this flag is
--keep-temp-files
(for thehaddock
subcommand).
5.5.5. Advanced global configuration options¶
-
write-ghc-environment-files
:
always, never, or ghc8.4.4+¶ -
--write-ghc-environment-files
=policy
¶ Default value: never
Whether a GHC package environment file should be created after a successful build.
Since Cabal 3.0, defaults to
never
. Before that, defaulted to creating them only when compiling with GHC 8.4.4 and older (GHC 8.4.4 is the first version that supports the-package-env -
option that allows ignoring the package environment files).
-
http-transport
:
curl, wget, powershell, or plain-http¶ -
--http-transport
=transport
¶ Default value: curl
Set a transport to be used when making http(s) requests.
The command line variant of this field is
--http-transport=curl
.
-
ignore-expiry
:
boolean¶ -
--ignore-expiry
¶ Default value: False If
True
, we will ignore expiry dates on metadata from Hackage.In general, you should not set this to
True
as it will leave you vulnerable to stale cache attacks. However, it may be temporarily useful if the main Hackage server is down, and we need to rely on mirrors which have not been updated for longer than the expiry period on the timestamp.The command line variant of this field is
--ignore-expiry
.
-
remote-repo-cache
:
directory¶ -
--remote-repo-cache
=DIR
¶ Default value: ~/.cabal/packages
[STRIKEOUT:The location where packages downloaded from remote repositories will be cached.] Not implemented yet.
The command line variant of this flag is
--remote-repo-cache=DIR
.
-
logs-dir
:
directory¶ -
--logs-dir
=DIR
¶ Default value: ~/.cabal/logs
[STRIKEOUT:The location where build logs for packages are stored.] Not implemented yet.
The command line variant of this flag is
--logs-dir=DIR
.
-
build-summary
:
template filepath¶ -
--build-summary
=TEMPLATE
¶ Default value: ~/.cabal/logs/build.log
[STRIKEOUT:The file to save build summaries. Valid variables which can be used in the path are
$pkgid
,$compiler
,$os
and$arch
.] Not implemented yet.The command line variant of this flag is
--build-summary=TEMPLATE
.
-
local-repo
:
directory¶ -
--local-repo
=DIR
¶ Deprecated: [STRIKEOUT:The location of a local repository.] Deprecated. See “Legacy repositories.”
The command line variant of this flag is
--local-repo=DIR
.
-
world-file
:
path¶ -
--world-file
=FILE
¶ Deprecated: [STRIKEOUT:The location of the world file.] Deprecated.
The command line variant of this flag is
--world-file=FILE
.
Undocumented fields: root-cmd
, symlink-bindir
, build-log
,
remote-build-reporting
, report-planned-failure
, one-shot
,
offline
.
Most users generally won’t need these.
-
solver
:
modular¶ -
--solver
=modular
¶ This field is reserved to allow the specification of alternative dependency solvers. At the moment, the only accepted option is
modular
.The command line variant of this field is
--solver=modular
.
-
max-backjumps
:
nat¶ -
--max-backjumps
=N
¶ Default value: 4000 Maximum number of backjumps (backtracking multiple steps) allowed while solving. Set -1 to allow unlimited backtracking, and 0 to disable backtracking completely.
The command line variant of this field is
--max-backjumps=4000
.
-
reorder-goals
:
boolean¶ -
--reorder-goals
¶ -
--no-reorder-goals
¶ Default value: False When enabled, the solver will reorder goals according to certain heuristics. Slows things down on average, but may make backtracking faster for some packages. It’s unlikely to help for small projects, but for big install plans it may help you find a plan when otherwise this is not possible. See #1780 for more commentary.
The command line variant of this field is
--(no-)reorder-goals
.
-
count-conflicts
:
boolean¶ -
--count-conflicts
¶ -
--no-count-conflicts
¶ Default value: True Try to speed up solving by preferring goals that are involved in a lot of conflicts.
The command line variant of this field is
--(no-)count-conflicts
.
-
minimize-conflict-set
:
boolean¶ -
--minimize-conflict-set
¶ -
--no-minimize-conflict-set
¶ Default value: False When there is no solution, try to improve the solver error message by finding a minimal conflict set. This option may increase run time significantly, so it is off by default.
The command line variant of this field is
--(no-)minimize-conflict-set
.
-
strong-flags
:
boolean¶ -
--strong-flags
¶ -
--no-strong-flags
¶ Default value: False Do not defer flag choices. (TODO: Better documentation.)
The command line variant of this field is
--(no-)strong-flags
.
-
allow-boot-library-installs
:
boolean¶ -
--allow-boot-library-installs
¶ -
--no-allow-boot-library-installs
¶ Default value: False By default, the dependency solver doesn’t allow
base
,ghc-prim
,integer-simple
,integer-gmp
, andtemplate-haskell
to be installed or upgraded. This flag removes the restriction.The command line variant of this field is
--(no-)allow-boot-library-installs
.
-
cabal-lib-version
:
version¶ -
--cabal-lib-version
=version
¶ This field selects the version of the Cabal library which should be used to build packages. This option is intended primarily for internal development use (e.g., forcing a package to build with a newer version of Cabal, to test a new version of Cabal.) (TODO: Specify its semantics more clearly.)
The command line variant of this field is
--cabal-lib-version=<IP_ADDRESS>
.