# Quick Start
Compile Solidity contracts.
## Dependencies
- [python3](https://www.python.org/downloads) version 3.9 up to 3.12.
## Installation
### via `pip`
You can install the latest release via [`pip`](https://pypi.org/project/pip/):
```bash
pip install ape-solidity
```
### via `setuptools`
You can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:
```bash
git clone https://github.com/ApeWorX/ape-solidity.git
cd ape-solidity
python3 setup.py install
```
## Quick Usage
In your project, make sure you have a `contracts/` directory containing Solidity files (`.sol`).
Then, while this plugin is installed, compile your contracts:
```bash
ape compile
```
The byte-code and ABI for your contracts should now exist in a `__local__.json` file in a `.build/` directory.
### Solidity Versioning
By default, `ape-solidity` tries to use the best versions of Solidity by looking at all the source files' pragma specifications.
However, it is often better to specify a version directly.
If you know the best version to use, set it in your `ape-config.yaml`, like this:
```yaml
solidity:
version: 0.8.14
```
### EVM Versioning
By default, `ape-solidity` will use whatever version of EVM rules are set as default in the compiler version that gets used.
Sometimes, you might want to use a different version, such as deploying on Arbitrum or Optimism where new opcodes are not supported yet.
If you want to require a different version of EVM rules to use in the configuration of the compiler, set it in your `ape-config.yaml` like this:
```yaml
solidity:
evm_version: paris
```
### Dependency Mapping
By default, `ape-solidity` knows to look at installed dependencies for potential remapping-values and will use those when it notices you are importing them.
For example, if you are using dependencies like:
```yaml
dependencies:
- name: openzeppelin
github: OpenZeppelin/openzeppelin-contracts
version: 4.4.2
```
And your source files import from `openzeppelin` this way:
```solidity
import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
```
Ape knows how to resolve the `@openzeppelin` value and find the correct source.
If you want to override this behavior or add new remappings that are not dependencies, you can add them to your `ape-config.yaml` under the `solidity:` key.
For example, let's say you have downloaded `openzeppelin` somewhere and do not have it installed in Ape.
You can map to your local install of `openzeppelin` this way:
```yaml
solidity:
import_remapping:
- "@openzeppelin=path/to/openzeppelin"
```
### Library Linking
To compile contracts that use libraries, you need to add the libraries first.
Use the `add_library()` method from the `ape-solidity` compiler class to add the library.
A typical flow is:
1. Deploy the library.
2. Call `add_library()` using the Solidity compiler plugin, which will also re-compile contracts that need the library.
3. Deploy and use contracts that require the library.
For example:
```python
import pytest
@pytest.fixture
def contract(accounts, project, compilers):
# Deploy the library.
account = accounts[0]
library = project.Set.deploy(sender=account)
# Add the library to Solidity (re-compiles contracts that use the library).
compilers.solidity.add_library(library)
# Deploy the contract that uses the library.
return project.C.deploy(sender=account)
```
### Compiler Settings
When using `ape-solidity`, your project's manifest's compiler settings will include standard JSON output.
You should have one listed `compiler` per `solc` version used in your project.
You can view your current project manifest, including the compiler settings, by doing:
```python
from ape import project
manifest = project.extract_manifest()
for compiler_entry in manifest.compilers:
print(compiler_entry.version)
print(compiler_entry.settings)
```
**NOTE**: These are the settings used during contract verification when using the [Etherscan plugin](https://github.com/ApeWorX/ape-etherscan).
#### `--via-IR` Yul IR Compilation Pipeline
You can enable `solc`'s `--via-IR` flag by adding the following values to your `ape-config.yaml`
```yaml
solidity:
via_ir: True
```
### Contract Flattening
`ape-solidity` has contract-flattening capabilities.
If you are publishing contracts using Ape, Ape automatically detects and uses the flattened-contract approach if needed.
To manually flatten a contract for your own benefit, use the following code:
```python
from ape import compilers, project
source_path = project.source_paths[0] # Replace with your path.
flattened_src = compilers.flatten_contract(source_path)
print(str(flattened_src))
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ApeWorX/ape-solidity",
"name": "ape-solidity",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": null,
"keywords": "ethereum",
"author": "ApeWorX Ltd.",
"author_email": "admin@apeworx.io",
"download_url": "https://files.pythonhosted.org/packages/1c/89/f8d20f8179b66e2fef7659b83d03bc937b478fb9d1882fd9c9d349e8a53d/ape-solidity-0.8.4.tar.gz",
"platform": null,
"description": "# Quick Start\n\nCompile Solidity contracts.\n\n## Dependencies\n\n- [python3](https://www.python.org/downloads) version 3.9 up to 3.12.\n\n## Installation\n\n### via `pip`\n\nYou can install the latest release via [`pip`](https://pypi.org/project/pip/):\n\n```bash\npip install ape-solidity\n```\n\n### via `setuptools`\n\nYou can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:\n\n```bash\ngit clone https://github.com/ApeWorX/ape-solidity.git\ncd ape-solidity\npython3 setup.py install\n```\n\n## Quick Usage\n\nIn your project, make sure you have a `contracts/` directory containing Solidity files (`.sol`).\n\nThen, while this plugin is installed, compile your contracts:\n\n```bash\nape compile\n```\n\nThe byte-code and ABI for your contracts should now exist in a `__local__.json` file in a `.build/` directory.\n\n### Solidity Versioning\n\nBy default, `ape-solidity` tries to use the best versions of Solidity by looking at all the source files' pragma specifications.\nHowever, it is often better to specify a version directly.\nIf you know the best version to use, set it in your `ape-config.yaml`, like this:\n\n```yaml\nsolidity:\n version: 0.8.14\n```\n\n### EVM Versioning\n\nBy default, `ape-solidity` will use whatever version of EVM rules are set as default in the compiler version that gets used.\nSometimes, you might want to use a different version, such as deploying on Arbitrum or Optimism where new opcodes are not supported yet.\nIf you want to require a different version of EVM rules to use in the configuration of the compiler, set it in your `ape-config.yaml` like this:\n\n```yaml\nsolidity:\n evm_version: paris\n```\n\n### Dependency Mapping\n\nBy default, `ape-solidity` knows to look at installed dependencies for potential remapping-values and will use those when it notices you are importing them.\nFor example, if you are using dependencies like:\n\n```yaml\ndependencies:\n - name: openzeppelin\n github: OpenZeppelin/openzeppelin-contracts\n version: 4.4.2\n```\n\nAnd your source files import from `openzeppelin` this way:\n\n```solidity\nimport \"@openzeppelin/contracts/token/ERC721/ERC721.sol\";\n```\n\nApe knows how to resolve the `@openzeppelin` value and find the correct source.\n\nIf you want to override this behavior or add new remappings that are not dependencies, you can add them to your `ape-config.yaml` under the `solidity:` key.\nFor example, let's say you have downloaded `openzeppelin` somewhere and do not have it installed in Ape.\nYou can map to your local install of `openzeppelin` this way:\n\n```yaml\nsolidity:\n import_remapping:\n - \"@openzeppelin=path/to/openzeppelin\"\n```\n\n### Library Linking\n\nTo compile contracts that use libraries, you need to add the libraries first.\nUse the `add_library()` method from the `ape-solidity` compiler class to add the library.\nA typical flow is:\n\n1. Deploy the library.\n2. Call `add_library()` using the Solidity compiler plugin, which will also re-compile contracts that need the library.\n3. Deploy and use contracts that require the library.\n\nFor example:\n\n```python\nimport pytest\n\n\n@pytest.fixture\ndef contract(accounts, project, compilers):\n # Deploy the library.\n account = accounts[0]\n library = project.Set.deploy(sender=account)\n\n # Add the library to Solidity (re-compiles contracts that use the library).\n compilers.solidity.add_library(library)\n\n # Deploy the contract that uses the library.\n return project.C.deploy(sender=account)\n```\n\n### Compiler Settings\n\nWhen using `ape-solidity`, your project's manifest's compiler settings will include standard JSON output.\nYou should have one listed `compiler` per `solc` version used in your project.\nYou can view your current project manifest, including the compiler settings, by doing:\n\n```python\nfrom ape import project\n\nmanifest = project.extract_manifest()\n\nfor compiler_entry in manifest.compilers:\n print(compiler_entry.version)\n print(compiler_entry.settings)\n```\n\n**NOTE**: These are the settings used during contract verification when using the [Etherscan plugin](https://github.com/ApeWorX/ape-etherscan).\n\n#### `--via-IR` Yul IR Compilation Pipeline\n\nYou can enable `solc`'s `--via-IR` flag by adding the following values to your `ape-config.yaml`\n\n```yaml\nsolidity:\n via_ir: True\n```\n\n### Contract Flattening\n\n`ape-solidity` has contract-flattening capabilities.\nIf you are publishing contracts using Ape, Ape automatically detects and uses the flattened-contract approach if needed.\n\nTo manually flatten a contract for your own benefit, use the following code:\n\n```python\nfrom ape import compilers, project\n\nsource_path = project.source_paths[0] # Replace with your path.\nflattened_src = compilers.flatten_contract(source_path)\nprint(str(flattened_src))\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Plugin for Ape Ethereum Framework for compiling Solidity contracts",
"version": "0.8.4",
"project_urls": {
"Homepage": "https://github.com/ApeWorX/ape-solidity"
},
"split_keywords": [
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e1cd0c1cf11ef383f888098a87f8854442bd203494f1a02326869b7ec290023a",
"md5": "65f0be0f90fd7ba88fe921d7c22f85ad",
"sha256": "05a8aba38f17eda7bf92dc9caf11c5dbce4cf20c7d3e98d8eb1ed06376c8e94b"
},
"downloads": -1,
"filename": "ape_solidity-0.8.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65f0be0f90fd7ba88fe921d7c22f85ad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9",
"size": 28815,
"upload_time": "2024-09-09T22:51:20",
"upload_time_iso_8601": "2024-09-09T22:51:20.223882Z",
"url": "https://files.pythonhosted.org/packages/e1/cd/0c1cf11ef383f888098a87f8854442bd203494f1a02326869b7ec290023a/ape_solidity-0.8.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c89f8d20f8179b66e2fef7659b83d03bc937b478fb9d1882fd9c9d349e8a53d",
"md5": "e02a0416305371990a87c3fbc913eaf5",
"sha256": "7e27a59f930792fcd92794eace7820f917a2d3cbb97f98a55994244b9e5b50e0"
},
"downloads": -1,
"filename": "ape-solidity-0.8.4.tar.gz",
"has_sig": false,
"md5_digest": "e02a0416305371990a87c3fbc913eaf5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9",
"size": 418157,
"upload_time": "2024-09-09T22:51:22",
"upload_time_iso_8601": "2024-09-09T22:51:22.421180Z",
"url": "https://files.pythonhosted.org/packages/1c/89/f8d20f8179b66e2fef7659b83d03bc937b478fb9d1882fd9c9d349e8a53d/ape-solidity-0.8.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-09 22:51:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ApeWorX",
"github_project": "ape-solidity",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ape-solidity"
}
JSON
